Agent Beacon

What is Agent Beacon

Agent Beacon is the world's first open-source telemetry layer for AI agents.

Agent activity is fragmented across runtimes and environments, from endpoints and CI to browsers and the cloud. Beacon captures that activity and normalizes agent telemetry into a single, unified schema.

Beacon supports 21+ local agent runtimes and every major surface agents run on. It ships as a lightweight endpoint binary and TypeScript SDK, installs with one command or fleet-wide through MDM, and forwards telemetry to major SIEM, observability, and data platforms.

Learn more in the Agent Beacon documentation.

High-Level Architecture

Beacon captures activity where each agent actually runs, then normalizes it into a single OpenTelemetry-based event model.

• Sources — local agents through hooks, plugins, and local OpenTelemetry; browser chat through an optional extension; agents in code through the TypeScript SDK; CI pipelines through a temporary collector; and cloud agents through sandbox hooks.
• Beacon — collect, normalize, store, correlate, and detect. Every surface lands in one event model, one durable JSONL log, one session timeline, and one local detection engine.
• Destinations — inspect events in the local dashboard, retain JSONL, or forward the same stream into the major enterprise-grade SIEMs, log aggregators, and object storage.

Collection, processing, and inspection stay local by default; the same normalized event model extends to CI, cloud-agent, and SDK paths under customer control. See the open-source architecture reference for the full breakdown by surface, or the system architecture overview to compare it with the managed path.

Supported Surfaces

Agent Runtimes

Local Agents

Browser Chat

CI Agents

Cloud Agents

Output Destinations

Beacon writes endpoint telemetry to local JSONL by default and supports customer-controlled forwarding into SIEM, log aggregation, and object storage destinations, plus an opt-in managed path to the Asymptote dashboard.

Asymptote Managed

Security Information and Event Management (SIEM)

Log Aggregation

Object Storage

Local

MDM Deployment

Every version tag publishes native packages that perform the system-mode install themselves: they register and start the service, write machine-wide configuration, and point the interactive user's agent runtimes at the local collector. Homebrew and release archives remain available for CLI installs.

The macOS package also ships GCS forwarder helpers under /opt/beacon/jamf/claude/gcs/ that run bundled Vector as a launchd job. Connecting a system-mode endpoint to Asymptote Managed is interactive today: an admin runs sudo beacon endpoint connect --system on the machine and approves it in the console user's browser. Headless enrollment tokens for MDM fleets are planned as a follow-up.

Dashboard and Local Detection

Beacon includes a local, read-only dashboard for validating endpoint activity without a hosted backend. It reads runtime.jsonl, where Beacon writes endpoint activity, alongside the sibling inventory_state.jsonl of periodic Cursor and Claude Code configuration inventory. Storage and retention behavior is summarized in the local testing and logs docs.

For offline threat detection, beacon scan runs open threat rules over local telemetry with no network access. See the Threat Rules spec and the generated rule field reference for rule format, CEL matching, fixtures, and supported event fields.

Start Here

• Beacon CLI docs — full documentation index.
• Installation — install Beacon locally.
• For Security & IT Teams — rollout, validation, and security workflows.
• Security review — architecture, data handling, and local-only posture.
• Endpoint agent — install, status, repair, and uninstall.
• Dashboard — inspect local runtime logs.
• Endpoint event schema — normalized JSONL event model.
• Supported surfaces — supported runtimes, destinations, and boundaries.
• Command reference — detailed CLI command docs.

Quickstart

See the Quickstart docs for the full setup paths.

First-Run Onboarding

The first time you run beacon endpoint install in a terminal, Beacon asks for your email and whether this is work or personal use, and sends that to Asymptote once. Knowing who runs Beacon is how we decide which runtimes and integrations to build next. It happens once per machine and never runs non-interactively: MDM deployments, package postinstall scripts, --system installs, CI, --dry-run, and piped stdin all skip it silently, and BEACON_ONBOARDING=0 turns it off. Exactly what is sent, and nothing else:

Never sent: prompts, file contents, commands, telemetry events, repository names, or anything else Beacon captures. The endpoint agent itself stays local-only; this is one HTTP request at install time, not an ongoing channel, unless you connect the machine to Asymptote Managed.

The same first-run prompt ends with one more question, where should this machine's agent telemetry go?, answered with the arrow keys:

• Keep it on this machine (the default, so Enter never forwards anything). Local JSONL and local dashboard.
• Forward to your own infrastructure: a SIEM, observability platform, or an S3/GCS bucket you own. Beacon points you at the log forwarding docs and the install stays local until you set up a pack.
• Forward to Asymptote Managed: runs beacon endpoint connect after the install. Your browser opens the Asymptote dashboard, a member of your organization approves this specific device, and a Vector forwarder starts shipping the runtime and inventory JSONL with a per-device key. Nothing recorded before the approval is sent, and the device can be revoked from the dashboard at any time.

The answer stays on the machine and is never sent. Local and own-infrastructure answers are recorded at once and the question is not asked again; the Asymptote answer is recorded once the machine is connected, so a failed install or connection is asked again on the next interactive install. beacon endpoint install --connect skips the question and connects; BEACON_MANAGED_INGEST=0 hides the Asymptote option. See beacon endpoint connect and Asymptote Managed forwarding.

See the first-run onboarding docs for fleet attribution without a terminal, inspecting or clearing the record, and deletion requests.

For Security & IT Teams

Start with the security and IT quickstart and managed deployment guidance for rollout, validation, retention, and SIEM forwarding. For vendor review, see the security review.

For Developers

Install the released CLI with Homebrew, or build from source. The Homebrew formula depends on the tap's own vector formula (Vector is not in homebrew-core), so a Homebrew install can connect to Asymptote Managed without a second step; on Linux, install the vector package from vector.dev if you want managed forwarding.

brew tap asymptote-labs/tap
brew install beacon
beacon version

cd cli/beacon
make build

To verify a change against a real Claude Code session rather than only synthetic payloads, beacon-sandbox runs one in a disposable Linux sandbox and checks what Beacon actually captured:

cd beacon-sandbox
go run ./cmd/beacon-sandbox doctor
go run ./cmd/beacon-sandbox run --scenario s02-bash-command

See Verify Beacon In A Sandbox for setup, coverage, and limitations.

The browser extension is a separate, optional component that builds on its own. It needs a running Beacon endpoint to post to, and its test suite replays recorded chat streams through the real extension in headless Chromium, so it needs no login and no network:

cd browser-extension
npm ci
npm run build          # load dist/ unpacked in Chrome
npm test               # replay e2e

See browser-extension/README.md for what it captures and retains.

Star Growth

License

MIT