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

# For Individual Developers

> Install Beacon on your machine, see what your AI coding agents are doing, and, if your team uses Asymptote, forward that telemetry to your team's dashboard in one step

Ten minutes, no admin rights. Beacon installs a small local collector under your user account,
records what Claude Code, Codex, Cursor and other supported agents do into a JSONL log on your
machine, and shows it to you in a local dashboard. If your team uses Asymptote Managed, the same
setup connects your machine to the team dashboard after a one-click approval in your browser.

Nothing leaves your machine unless you choose to forward it; see [what leaves your machine](#what-leaves-your-machine).

## 1. Install Beacon

<CodeGroup>
  ```bash title="macOS" theme={null}
  brew install asymptote-labs/tap/beacon
  ```

  ```bash title="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 -m)" in
    x86_64) ARCH=amd64 ;;
    aarch64|arm64) ARCH=arm64 ;;
    *) echo "Beacon publishes Linux archives for amd64 and arm64, not $(uname -m)" >&2; exit 1 ;;
  esac

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

  grep "  ${ARCHIVE}$" checksums.txt | sha256sum --check -

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

Homebrew also installs [Vector](https://vector.dev), which Beacon uses to forward telemetry when you
ask it to. On Linux, install Vector 0.50 or newer from vector.dev if you plan to forward.

<Note>
  The Linux tab uses the tarball on purpose. This page is a per-user setup; the `.deb`/`.rpm`
  packages install a **system-mode** endpoint managed by systemd that writes to
  `/var/log/beacon-agent/runtime.jsonl`, so the commands below would report on the wrong log. For
  the system-mode package, follow [Linux](/platforms/linux) instead.
</Note>

## 2. Set up the endpoint

```bash theme={null}
beacon endpoint install
```

This starts the local collector, discovers supported runtimes on your machine, and configures every integration Beacon can safely install. Use an explicit `--harness` list only when you want exact selection, or `--harness all` to force every installable integration (see [Runtime hooks](/cli/hooks) for hook runtime names).

The first install runs a terminal wizard. It may ask how you are using Beacon and your email for setup attribution, then asks where this machine's agent telemetry should go:

| Choice | What happens |
| - | - |
| **Asymptote Managed** (default) | Beacon shows what will be sent, asks for Standard or Metadata-only privacy, installs locally, and then connects this endpoint. The confirmation screen states that forwarding starts and that the last 30 days of agent sessions are uploaded before you accept. |
| **Local only** | Nothing is sent anywhere. You get the local log and the local dashboard. Change your mind any time with `beacon endpoint connect` or a forwarding pack. |

The answers stay on your machine and are asked once per machine. The one exception: if you chose
Asymptote Managed and the connection did not finish, the destination question comes back next time.

## 3. If you chose Asymptote Managed

You need to be a member of your organization in Asymptote; ask an admin for an invite if signing in
shows no organization. After the install finishes:

1. Sign in if asked.
2. User-mode connects with your signed-in CLI account. System-mode enrollment opens a browser approval page showing your machine's name, OS, and Beacon version.
3. Back in the terminal you see `Connected to Asymptote as device … for <your org>` and
   `Forwarder: … running=true`. The per-device key is stored in a file only you can read; it is
   never printed.

Skipped the question or your browser did not open? Run it any time:

```bash theme={null}
beacon endpoint connect
```

## 4. See your first events

Start a new Claude Code or Codex session, or restart Cursor so it loads the hooks, and do a few
turns. Then:

```bash theme={null}
beacon endpoint status              # collector running, each harness telemetry=enabled
beacon endpoint dashboard --open    # local dashboard over your own log
```

If you connected to Asymptote Managed, your machine appears on the team dashboard's **Endpoints**
page within a minute or two, and the session shows up under **Telemetry**. The `status` output
also has an `Asymptote managed ingest` line with the connection, the forwarder state, and whether
the device key is still accepted.

## Everyday commands

| Task | Command |
| - | - |
| Check health and the managed connection | `beacon endpoint status` |
| Local dashboard | `beacon endpoint dashboard --open` |
| Connect to Asymptote Managed later, or re-connect after a revoke | `beacon endpoint connect` |
| Stop forwarding and remove the local key | `beacon endpoint disconnect`, then revoke the device on the dashboard |
| See what you answered at setup | `beacon endpoint onboarding` |
| Hook status for a runtime | `beacon endpoint hooks status --harness cursor` |
| Upgrade | `brew upgrade beacon && beacon endpoint install` (the forwarder keeps running) |
| Remove everything, keep your logs | `beacon endpoint uninstall --keep-logs` |

## What leaves your machine

* **Local-only choice:** hooks and the collector never touch the network unless you connect or configure a forwarding pack.
* **Once, at setup:** your email, your work/personal answer, and install context (OS, architecture,
  Beacon version, install method, detected runtime names, a random install id). Never prompt text,
  commands, file contents, or events. `BEACON_ONBOARDING=0` skips it entirely.
* **Only if you connected to Asymptote Managed:** runtime and inventory logs are sent by Vector with your device key according to the selected privacy mode. A bounded 30-day session backfill is uploaded on connect so the dashboard has recent sessions. Revoking the device on the dashboard stops it within about a minute; `beacon endpoint disconnect` stops it locally.

## If something looks off

* **No events after a session:** Claude Code and Codex read their telemetry settings at startup, and
  Cursor loads hooks at startup, so start a fresh session or restart the app.
* **`status` says the credential is revoked:** someone revoked this device, or you left the
  organization. `beacon endpoint connect` re-enrolls.
* **The approval page says "not provisioned" or "not enabled":** you are not yet a member of an
  organization that has managed ingest, or none is enabled. Ask your admin.
* **`Collector ports are not listening` during install:** another collector is already using one of the required ports. Use a different OTLP port pair, for example `--otlp-grpc-port 4327 --otlp-http-port 4328`, or use the existing system install. See [troubleshooting](/support/troubleshooting).

## Related

<Columns cols={2}>
  <Card title="beacon endpoint connect" icon="link" href="/cli/endpoint-connect">
    Everything about connecting, disconnecting, and what the forwarder stores.
  </Card>

  <Card title="Asymptote Managed forwarding" icon="tower-broadcast" href="/log-forwarding/asymptote">
    The wire contract, what is sent, and how revocation works.
  </Card>

  <Card title="Runtime hooks" icon="plug" href="/cli/hooks">
    Install, check, and remove hook-based telemetry for each runtime.
  </Card>

  <Card title="Log forwarding" icon="share-nodes" href="/log-forwarding">
    Send the local log to your own SIEM, observability platform, or bucket.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.