> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual CLI Installation

> Install the Beacon CLI from platform archives or build it from source

## 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.

```bash title="Download, verify, and extract (macOS or Linux)" theme={null}
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:

```bash title="Build Beacon from source" theme={null}
git clone https://github.com/asymptote-labs/agent-beacon.git
cd agent-beacon/cli/beacon
make build
```

## Related

<Columns cols={2}>
  <Card title="Install Beacon" icon="download" href="/cli/install">
    Install Beacon with Homebrew.
  </Card>

  <Card title="Endpoint telemetry" icon="satellite-dish" href="/cli/endpoint-install">
    Configure local agent harness telemetry after installing the CLI.
  </Card>
</Columns>