Skip to main content
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.

​
1. Install Beacon

Homebrew also installs Vector, 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.
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 instead.

​
2. Set up the endpoint

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 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: 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:

​
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:
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

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

beacon endpoint connect

Everything about connecting, disconnecting, and what the forwarder stores.

Asymptote Managed forwarding

The wire contract, what is sent, and how revocation works.

Runtime hooks

Install, check, and remove hook-based telemetry for each runtime.

Log forwarding

Send the local log to your own SIEM, observability platform, or bucket.