Beacon CLI

Local endpoint telemetry for AI agent runtimes

Beacon CLI

Beacon is Asymptote’s open-source endpoint agent for local AI runtime telemetry. It captures supported activity from Claude Code, Codex CLI, Claude Cowork, and Cursor, then normalizes it into Wazuh-compatible JSONL for existing localfile/Wazuh pipelines, customer-managed forwarding, or optional Splunk HEC export.

For the product vision and motivation behind Beacon, read Introducing Beacon: Endpoint Telemetry for AI Agents.

Install Beacon

Install the beacon CLI with Homebrew and configure the local endpoint agent.

What Beacon does

Beacon is visibility-first. The public build focuses on observing local AI agent runtime activity, normalizing it into endpoint events, preserving a local JSONL audit log, and forwarding to Wazuh localfile, Splunk HEC, or customer-managed pipelines.

• Discovers local AI runtimes including Claude Code, Codex CLI, Cursor, and Claude Cowork
• Configures Claude Code and Codex CLI to export OpenTelemetry to a local collector, with Codex prompt logging disabled and noisy internal transport spans filtered
• Installs Cursor hooks for session, prompt, tool, command, approval, MCP-like, and file edit events where Cursor exposes hook payloads
• Converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL
• Writes Wazuh-compatible JSONL to a local runtime log
• Optionally forwards logs, traces, and metrics to a customer-managed Splunk HTTP Event Collector
• Runs a local-only dashboard for runtime inventory, summaries, timelines, filters, and event details
• Generates Wazuh localfile, rule, and validation content for the Beacon event schema

Architecture and reference

Beacon architecture

Learn how local AI runtime telemetry flows through collection, normalization, and local outputs.

Endpoint event schema

Review Beacon JSONL fields, normalization behavior, and example events.

Supported surfaces

See supported runtimes, deployment modes, destinations, MDM guidance, and current boundaries.

For Security & IT Teams

Plan MDM deployment, inventory, validation, retention, and SIEM forwarding.

Quick start

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

Command reference

Common Beacon commands:

beacon version
beacon endpoint install
beacon endpoint status
beacon endpoint status --json
beacon endpoint discover
beacon endpoint discover --json
beacon endpoint repair
beacon endpoint dashboard --open
beacon endpoint dashboard --addr 127.0.0.1:8765
beacon endpoint wazuh print-config
beacon endpoint wazuh install-pack --output ./beacon-wazuh
beacon endpoint wazuh validate
beacon endpoint install --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token "$SPLUNK_HEC_TOKEN" --splunk-index beacon
beacon endpoint hooks install --harness cursor
beacon endpoint hooks status --harness cursor
beacon endpoint integrations claude-cowork setup --endpoint https://collector.example.com --open
beacon endpoint integrations claude-cowork validate --since 10m
beacon endpoint uninstall --keep-logs

Endpoint commands use per-user paths by default so hook and OTLP telemetry share ~/.beacon/endpoint/logs/runtime.jsonl. Use --system for root-managed package or MDM deployments.

Setup and operation

Installation

Install Beacon and understand the files it manages.

Endpoint agent

Install, repair, inspect, and uninstall the local endpoint agent.

MDM deployment

Deploy Beacon with Jamf Pro, Fleet, or another macOS MDM.

Jamf

Deploy and inventory Beacon with Jamf Pro.

Fleet

Deploy and inventory Beacon with Fleet.

SIEM forwarding

Forward Beacon events into Wazuh, Splunk HEC, or customer-managed pipelines.

Dashboard

Run the localhost dashboard over Beacon runtime logs.

Wazuh

Print Wazuh config, generate a content pack, and validate events.

Cursor hooks

Install, check, and remove hook-based endpoint telemetry.

Claude Cowork

Set up and validate Claude Cowork OTLP export.

Privacy and retention

Beacon records configured content fields by default. Content retention is configurable with --content-retention full, --content-retention redacted, or --content-retention metadata.

• 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

See the Endpoint event schema page for content-retention fields, truncation behavior, and a complete example event.

Beacon does not currently provide kernel or process monitoring, shell history collection, cloud audit ingestion, browser or SaaS telemetry, credential-use attribution, MCP configuration inventory, or direct Datadog/Elastic exporters. Use SIEM forwarding to route Beacon events to Wazuh, Splunk HEC, or another customer-managed pipeline.