Quickstart

1. Install Beacon

macOS
Windows
Linux

brew update
brew trust asymptote-labs/tap
brew install asymptote-labs/tap/beacon

Download BeaconEndpointAgent-<version>-x64.msi from the latest release, then run PowerShell as an administrator:

msiexec /i BeaconEndpointAgent-<version>-x64.msi

See the Windows install guide for more options.

Install the latest .deb or .rpm for your distribution and architecture:

curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash

The installer verifies the package against the release checksums before installing it. See the Linux install guide for manual package, tarball, and rootless installs.

Then configure the agents you use:

beacon endpoint install --harness claude,codex,cursor

2. Choose where your data lives

Beacon supports two modes.

Local

Keep your agent history on your machine. Beacon writes telemetry locally and gives you a local dashboard. Nothing is forwarded unless you explicitly configure it.

Beacon Cloud

Send your Beacon telemetry to the hosted service for:

unlimited retention
search across past sessions
cross-harness history
analytics
access from anywhere

Interactive installation signs in, preselects Beacon Cloud, and asks you to review the privacy choice. Confirming installs Beacon and connects this endpoint in the same command, using the signed-in CLI account to authorize a separate device ingest key with no second browser approval. If you chose Local during setup, or enrollment did not succeed, connect later with:

beacon endpoint connect

Use --privacy-mode metadata-only to override Standard.

3. Run an agent

Start a session in a runtime you configured. The default endpoint install configures Claude Code and Codex CLI. Cursor and other supported runtimes require their documented hook, plugin, OTLP, or session-sync setup; see Agent harnesses. Once that runtime surface is configured, Beacon captures the telemetry the runtime exposes through it.

4. View your sessions

For the local dashboard:

beacon endpoint dashboard --open

If you’re using Beacon Cloud, your sessions will also appear in the hosted dashboard, which the install opens when setup finishes, at beacon.sh/dashboard.

Check your setup

beacon endpoint status

This shows which harnesses are connected, whether the collector is running, and whether Beacon Cloud is enabled.

Useful commands

Task	Command
Check status	`beacon endpoint status`
Open local dashboard	`beacon endpoint dashboard --open`
Connect to Beacon Cloud	`beacon endpoint connect`
Disconnect from Beacon Cloud	`beacon endpoint disconnect`
Upgrade	`brew update && brew upgrade beacon`
Uninstall	`beacon endpoint uninstall --keep-logs`

Get Started

Deploy Beacon

Beacon Cloud

Sharing Sessions

How Beacon Works

Agent Harness Integrations

Support

Contributing

1. Install Beacon

2. Choose where your data lives

Local

Beacon Cloud

3. Run an agent

4. View your sessions

Check your setup

Useful commands

​1. Install Beacon

​2. Choose where your data lives

​Local

​Beacon Cloud

​3. Run an agent

​4. View your sessions

​Check your setup

​Useful commands

1. Install Beacon

2. Choose where your data lives

Local

Beacon Cloud

3. Run an agent

4. View your sessions

Check your setup

Useful commands