Skip to main content
Install Beacon with Homebrew, configure the local endpoint telemetry path, and use the repair workflow when you need to reapply configuration after an upgrade. For CI, cloud-agent, and SDK setup paths, see Agent harness integrations.

​
Install Beacon

Install Beacon
brew tap asymptote-labs/tap
brew install beacon
beacon version
beacon version output
$ beacon version
beacon version 0.0.48

​
Configure endpoint telemetry

For most individual developer setups, continue with the default per-user endpoint install:
Configure endpoint telemetry
beacon endpoint install
beacon endpoint status
By default, Beacon configures Claude Code and Codex CLI to export telemetry to a local OpenTelemetry Collector on 127.0.0.1. Add Gemini when you want Beacon to manage Gemini OTLP settings too:
Include Gemini telemetry
beacon endpoint install --harness claude,codex,gemini
Production endpoint install is currently supported on macOS. The default mode uses per-user paths; use --system as root for package or MDM deployments.
Beacon records supported prompt, tool, command, file, approval, policy, and runtime context when the source runtime emits it. Before events are written to runtime.jsonl or sent through configured destinations, Beacon applies redaction, sanitization, truncation, and event-size limits. Beacon filters generic process/runtime OTLP metrics, Copilot CLI and OpenClaw operational metrics, and high-volume Codex spans out of the local JSONL log by default. Use --include-runtime-metrics or --include-codex-spans only when troubleshooting.

​
Upgrade Beacon

Use the standard Homebrew upgrade flow, then reapply endpoint configuration if needed:
Upgrade Beacon
beacon version check
brew update
brew upgrade beacon
beacon endpoint repair
beacon endpoint repair reapplies managed service files, collector configuration, harness telemetry settings, and forwarding destinations while preserving runtime logs. On v0.0.43 or newer, use beacon endpoint doctor --fix when you only need supported health-check drift remediated without a full repair.

Hosting Options

Choose between Asymptote Cloud and the open-source Agent Beacon path.

Endpoint paths and ports

Review files, logs, collector config, ports, and hook locations.

Endpoint command reference

Review install, status, repair, and uninstall commands.

Endpoint repair

Reapply service files and telemetry configuration.

Manual CLI installation

Install from platform archives or build the CLI from source.