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
beacon version output

​
Configure endpoint telemetry

Setting up the endpoint differs by operating system. Start with your platform if you want the packages, service management, and fleet deployment for it:

macOS

Homebrew, or the signed .pkg for MDM. launchd.

Linux

.deb and .rpm packages. systemd.
The per-user install below works the same on both, and is the quickest way to try it on one machine:
Configure endpoint telemetry
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
System-mode install (--system) is supported on macOS and on Linux distributions that use systemd. The default mode uses per-user paths; use --system as root for package or MDM deployments. On Linux, installing the .deb or .rpm does the system install for you. See Linux.
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 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.