Installation

Install Beacon and configure local AI runtime telemetry

Installation

Install the Beacon CLI with Homebrew, then configure the local endpoint agent. Endpoint commands use per-user paths by default.

Install Beacon

brew tap asymptote-labs/tap
brew install beacon

Verify the CLI:

beacon version

Example output

$ beacon version
beacon version 0.0.4

Configure endpoint telemetry

For a non-root local setup, run the default install:

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.

Production endpoint install is currently supported on macOS. The default mode uses per-user paths; use --system as root for package or MDM deployments.

Installation paths

Beacon manages different paths depending on whether you install in user mode or system mode.

Item	User mode	System mode
Config	~/.beacon/endpoint/config.json	/Library/Application Support/Beacon/Endpoint/config.json
Base directory	~/.beacon/endpoint	/Library/Application Support/Beacon/Endpoint
Runtime log	~/.beacon/endpoint/logs/runtime.jsonl	/var/log/beacon-agent/runtime.jsonl
Collector config	~/.beacon/endpoint/otelcol.yaml	/Library/Application Support/Beacon/Endpoint/otelcol.yaml
OTLP gRPC	127.0.0.1:4317	127.0.0.1:4317
OTLP HTTP	127.0.0.1:4318	127.0.0.1:4318

Cursor hooks install an embedded beacon-hooks adapter under the Beacon endpoint base directory and write hook configuration to ~/.cursor/hooks.json for user-level installs or ./.cursor/hooks.json for project-level installs.

Content retention

By default, Beacon records configured content fields in local or customer-controlled logs. Use metadata when you want endpoint events to exclude prompt text, raw attributes, command output, and raw diffs:

beacon endpoint install --content-retention metadata

Supported retention modes:

• full: default; includes configured content fields in local or customer-controlled logs, still subject to event size limits
• redacted: includes configured content fields after local redaction and size limits
• metadata: excludes prompt text, raw attributes, command output, and raw diffs

Manual archives

Beacon releases publish platform archives for macOS and Linux on amd64 and arm64. Each archive includes the beacon CLI and the matching beacon-otelcol collector binary, with SHA-256 checksums published alongside the release.

Build from source

To build the CLI directly from the Beacon repository:

git clone https://github.com/Asymptote-Labs/agent-beacon.git
cd agent-beacon/cli/beacon
make build

Upgrading

Upgrade the Homebrew package, then repair endpoint configuration if you need to reapply service files or telemetry settings:

brew update
brew upgrade beacon
beacon endpoint repair

Next: Endpoint agent

Review the endpoint install, status, repair, and uninstall commands.