Manual CLI Installation

Archive collection

Beacon releases publish platform archives for macOS and Linux on amd64 and arm64, plus a .zip for Windows. Each archive contains three binaries: the beacon CLI, the beacon-hooks adapter that captures tool activity, and the matching beacon-otelcol collector. SHA-256 checksums are published alongside the release in checksums.txt. All three matter. beacon-hooks is what supported runtimes invoke to record prompts, tool calls, and approvals, so an install that keeps only the CLI and the collector captures OpenTelemetry data and nothing from the hook path.

Download, verify, and extract (macOS or Linux)

LATEST_URL="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"
VERSION="${LATEST_URL##*/v}"

case "$(uname -s)" in
  Linux) OS=linux ;;
  Darwin) OS=darwin ;;
  *) echo "Beacon publishes macOS and Linux archives, not $(uname -s)" >&2; exit 1 ;;
esac

case "$(uname -m)" in
  x86_64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
  *) echo "Beacon publishes amd64 and arm64 archives, not $(uname -m)" >&2; exit 1 ;;
esac

ARCHIVE="beacon_${VERSION}_${OS}_${ARCH}.tar.gz"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${ARCHIVE}"
curl -fsSLO "${BASE}/checksums.txt"

# Verify this exact archive before extracting it. macOS ships shasum rather than sha256sum.
if [ "$OS" = darwin ]; then
  grep "  ${ARCHIVE}$" checksums.txt | shasum -a 256 -c -
else
  grep "  ${ARCHIVE}$" checksums.txt | sha256sum --check -
fi

tar -xzf "${ARCHIVE}"
mkdir -p ~/.local/bin && mv beacon beacon-hooks beacon-otelcol ~/.local/bin/
beacon version

The version comes from the current release rather than a number to keep up to date, and the platform and architecture come from uname: x86_64 maps to the published amd64 archive and aarch64 to arm64. A platform or architecture Beacon does not publish stops the run before anything is downloaded. The checksum step names the one archive about to be extracted, so it verifies that file rather than whatever else the directory happens to hold. The archive layout is identical across platforms. For managed endpoint rollouts on Apple Silicon Macs, GitHub Releases also attach a signed, notarized, and stapled BeaconEndpointAgent-<version>-arm64.pkg. The package installs Beacon under /opt/beacon, includes the collector and Vector binary, and is intended for MDM or root-managed system deployments rather than per-user CLI installs.

Build from source

To build the CLI directly from the Beacon repository:

Build Beacon from source

git clone https://github.com/Asymptote-Labs/agent-beacon.git
cd agent-beacon/cli/beacon
make build

Install Beacon

Install Beacon with Homebrew.

Endpoint telemetry

Configure local agent harness telemetry after installing the CLI.

Install and Upgrade

CLI Resources

Command Manual

Manual CLI Installation

Archive collection

Build from source

Install Beacon

Endpoint telemetry

​Archive collection

​Build from source

​Related

Install Beacon

Endpoint telemetry

Archive collection

Build from source

Related