> ## Documentation Index > Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # beacon endpoint install > Install or update the local Beacon endpoint collector and runtime telemetry ## Command overview `beacon endpoint install` configures the local endpoint agent, writes the OpenTelemetry Collector configuration, installs the collector service, configures selected agent harnesses, and optionally adds Splunk HEC or Falcon LogScale HEC collector destinations. The service is a launchd job on macOS and a systemd unit on Linux. Where neither is available, Beacon runs a supervised collector instead and says so. See [macOS](/platforms/macos) or [Linux](/platforms/linux) for the platform setup, including the Linux packages and the `--service` flag. ```bash title="Command syntax" theme={null} beacon endpoint install ``` By default, Beacon discovers the runtimes installed for the invoking user and configures every integration it can safely install. This includes supported OTLP settings, hooks, plugins, or extensions. An explicit `--harness` list disables automatic selection and configures only the runtimes it names, while `--harness all` forces every installable integration. If discovery finds no automatically installable runtime, Beacon installs the collector without changing runtime configuration. Discovery can also find runtimes whose collection path cannot be enabled safely by a machine-wide default. Beacon reports these without treating them as install failures: GitHub Copilot CLI needs launch-environment settings, Claude Cowork needs admin configuration, poll-only fx needs `beacon endpoint fx sync`, and OpenHands CLI/GUI coverage requires project-level hooks installed from inside each repository. Factory Droid's hooks are installed automatically when Droid is detected, while its separate OTLP endpoint remains launch-environment managed. The `claude` harness writes both Claude Code's OpenTelemetry settings and user-level hooks, because the OTLP export alone carries no session start or end, file activity, or subagent lifecycle. `beacon endpoint hooks uninstall --harness claude` removes those hooks again, and `beacon endpoint hooks install --harness claude --level project` adds project-level hooks. Codex uses OTLP logs plus one selective turn trace for tokens, and its required SessionStart hook adds local OS-user context. Beacon applies redaction, sanitization, truncation, and event-size limits before writing supported content fields. ## Flags | Flag | Description | | - | - | | `--user` | Use per-user endpoint paths. Enabled by default | | `--system` | Use system endpoint paths and launch daemon. Requires root | | `--log-path ` | Runtime JSONL log path | | `--harness ` | Harnesses to configure. Defaults to `auto`, which installs every detected integration Beacon can configure and reports detected manual or poll-only integrations. Use `all` to force every installable integration, or pass an exact comma-separated list such as `claude,codex,cursor,kimi`. DeepSeek Harness and Kimi Code are user-level only. An explicit list preserves exact-selection behavior | | `--otlp-grpc-port ` | Local OTLP gRPC port. Defaults to `4317` | | `--otlp-http-port ` | Local OTLP HTTP port. Defaults to `4318` | | `--health-port ` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that changes, so a second collector on alternate OTLP ports does not collide with the first | | `--collector ` | Path to a `beacon-otelcol` binary | | `--no-start` | Write files without starting the collector service | | `--no-browser` | During interactive setup, print the sign-in URL instead of opening a browser. Useful where no browser can be opened | | `--service ` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process | | `--dry-run` | Print planned actions without changing endpoint files or services | | `--include-runtime-metrics` | Include generic process, runtime, and harness operational OTLP metrics in Beacon JSONL. By default, low-signal metrics such as process CPU, memory, Node.js event loop, V8 heap, GitHub Copilot CLI, and OpenClaw operational metrics are filtered out | | `--include-codex-spans` | Include every high-volume Codex OTLP span for troubleshooting. By default, Beacon keeps semantic logs and only the usage-bearing completed turn span | | `--claude-capture-model-context` | Record context Claude Code gives the model that no other event reports: pages its WebFetch tool fetches and MCP tool descriptions it shows the model as `mcp.tool_listed`. Turns on Claude Code's API-body logs; the collector keeps only that context and drops every body. Off by default. See [Claude Code: model context from API bodies](/runtimes/claude-code#model-context-from-api-bodies) | | `--splunk-hec-endpoint ` | Splunk HEC endpoint URL | | `--splunk-hec-token ` | Splunk HEC token | | `--splunk-index ` | Optional Splunk index | | `--splunk-source ` | Optional Splunk source | | `--splunk-sourcetype ` | Optional Splunk sourcetype | | `--splunk-insecure-skip-verify` | Skip Splunk HEC TLS certificate verification | | `--splunk-ca-file ` | Optional CA certificate path for Splunk HEC TLS verification | | `--falcon-hec-endpoint ` | Falcon LogScale HEC endpoint URL | | `--falcon-hec-token ` | Falcon LogScale ingest token | | `--falcon-index ` | Optional Falcon LogScale repository for multi-repository tokens | | `--falcon-source ` | Optional Falcon LogScale source | | `--falcon-sourcetype ` | Optional Falcon LogScale parser or sourcetype | | `--falcon-insecure-skip-verify` | Skip Falcon LogScale HEC TLS certificate verification | | `--falcon-ca-file ` | Optional CA certificate path for Falcon LogScale HEC TLS verification | | `--no-backfill` | Skip the [session backfill](#session-backfill). `BEACON_BACKFILL=0` does the same | | `--connect` | After a successful install, connect this endpoint to Asymptote managed ingest: opens the dashboard to approve the device and starts the Vector forwarder. Same as running [`beacon endpoint connect`](/cli/endpoint-connect) afterwards | ## Session backfill After a successful install, user or system mode, Beacon reads the last 30 days of agent sessions from each runtime's own session store into the runtime log, so the [local dashboard](/cli/dashboard) has recent sessions before any agent runs again. It is the same sweep each runtime's sync command runs, including Claude Code, Codex, Cursor, OpenCode, Copilot, Cline, Factory, Pi-family, Hermes, DeepSeek, fx, Grok, and OpenClaw session sync. Its events carry `harness.collection_method=poll`. The sweep is local and never touches the network. The backfill is bounded so a machine with a lot of history cannot crowd live telemetry out of the runtime log's rotation window: * Only sessions modified in the last 30 days are read, newest first. * It writes at most 24 MiB in total, and no single runtime takes more than 12 MiB of that. Nothing past a limit is lost. The collector cursors move only past what was written, and sessions left out are not touched, so the runtime's sync command reads the rest; install names the command for each runtime that hit the limit. A runtime whose store cannot be read is reported as a warning and never fails the install. Re-running install reads only what changed since the last sweep. A system, package, or MDM install reads the active console user's session stores rather than root's home. Because root is reading a user-controlled home, the read is confined to that home: links that lead out of it, files the user does not own, and FIFOs, sockets, or devices are skipped rather than read. SQLite stores are read from a private bounded copy. When nobody is logged in, install says the backfill was skipped and the next connect or manual sync can read the sessions. `--dry-run` installs skip it, and `--no-backfill` or `BEACON_BACKFILL=0` turn it off. ## Interactive onboarding wizard On a first interactive install the [onboarding wizard](/cli/endpoint-onboarding) signs in, then asks where this machine's telemetry should go: | Answer | What happens | | - | - | | Asymptote Managed (default) | Shows what will be sent, asks for Standard or Metadata-only privacy, then installs Beacon and connects this endpoint. The confirm screen states that forwarding starts and that the last 30 days of agent sessions are uploaded before you accept. | | Local only | Explicitly opts out of managed forwarding. Nothing is sent anywhere; the session backfill stays in the local log. | `--connect` presets Asymptote Managed and skips the destination question. Whether connect was chosen in the wizard or by the flag, a failed enrollment leaves the completed local install exiting successfully and prints `beacon endpoint connect` as the retry command. Automation should verify `.managed_ingest.connected` with `beacon endpoint status --json`. `BEACON_MANAGED_INGEST=0` hides the managed answer. The wizard is never shown for system/root, package, MDM, CI, dry-run, or redirected-input installs. Customer-managed destinations remain available through the [log forwarding packs](/log-forwarding) after choosing Local. ## Examples Install with the default per-user paths: ```bash title="Install with the default per-user paths" theme={null} beacon endpoint install ``` Install without starting the collector service: ```bash title="Install without starting the collector service" theme={null} beacon endpoint install --no-start ``` Configure only one harness: ```bash title="Configure only one harness" theme={null} beacon endpoint install --harness claude ``` Override discovery with an exact harness list: ```bash title="Configure an exact harness list" theme={null} beacon endpoint install --harness claude,codex,gemini ``` Force every installable integration without checking whether its runtime is present: ```bash title="Configure all supported integrations" theme={null} beacon endpoint install --harness all ``` Configure VS Code Copilot telemetry: ```bash title="Configure VS Code Copilot telemetry" theme={null} beacon endpoint install --harness vscode ``` Configure Devin CLI and Devin Desktop hooks alongside the default OTLP harnesses: ```bash title="Configure Devin CLI and Devin Desktop hooks alongside the default OTLP harnesses" theme={null} beacon endpoint install --harness claude,codex,devin-cli,devin-desktop ``` Include low-level runtime OTLP metrics that are filtered from JSONL by default: ```bash title="Include low-level runtime OTLP metrics that are filtered from JSONL by default" theme={null} beacon endpoint install --include-runtime-metrics ``` Include raw Codex spans for troubleshooting: ```bash title="Include raw Codex spans for troubleshooting" theme={null} beacon endpoint install --include-codex-spans ``` Install with system paths for a root-managed package or MDM deployment: ```bash title="Install with system paths for a root-managed package or MDM deployment" theme={null} sudo beacon endpoint install --system --harness claude,codex ``` Install and forward to CrowdStrike Falcon LogScale HEC: ```bash title="Install and forward to CrowdStrike Falcon LogScale HEC" theme={null} sudo beacon endpoint install \ --system \ --falcon-hec-endpoint https://cloud..humio.com/api/v1/ingest/hec \ --falcon-hec-token "$FALCON_HEC_TOKEN" \ --falcon-index beacon ``` Configure Factory Droid's OTLP endpoint through MDM or another customer-owned launch policy: ```bash title="Configure Factory Droid's OTLP endpoint through MDM or another customer-owned launch policy" theme={null} export OTEL_TELEMETRY_ENDPOINT="http://127.0.0.1:4318" droid exec "review this repository" ``` Configure GitHub Copilot CLI's OTLP endpoint through MDM or another customer-owned launch policy: ```bash title="Configure GitHub Copilot CLI's OTLP endpoint through MDM or another customer-owned launch policy" theme={null} export COPILOT_OTEL_ENABLED="true" export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318" ``` For richer hook telemetry, install runtime hooks after the endpoint configuration exists: ```bash title="Install runtime hooks" theme={null} beacon endpoint hooks install --harness antigravity,claude,cline,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen ``` Claude Code hooks are already installed at the user level by `endpoint install`. Add project-level hooks, or re-add user-level ones after removing them: ```bash title="Add Claude Code hooks to a project" theme={null} beacon endpoint hooks install --harness claude --level project ``` Install Grok Build hooks at the user level: ```bash title="Install Grok Build hooks at the user level" theme={null} beacon endpoint hooks install --harness grok ``` Install Hermes Agent hooks at the user level: ```bash title="Install Hermes Agent hooks at the user level" theme={null} beacon endpoint hooks install --harness hermes ``` Hermes hooks write `~/.hermes/config.yaml` and support user-level installs only. Install Qwen Code hooks at the user level: ```bash title="Install Qwen Code hooks at the user level" theme={null} beacon endpoint hooks install --harness qwen ``` Qwen Code hooks merge into `~/.qwen/settings.json`. Qwen Code has no OpenTelemetry export to configure, so `qwen` is a hook harness on this command too: `beacon endpoint install --harness qwen` installs the same hooks and writes `~/.qwen/settings.json`. Project-level Grok Build hooks write `./.grok/hooks/beacon-endpoint.json` and require `/hooks-trust` in Grok before they execute: ```bash title="Install project-level Grok Build hooks" theme={null} beacon endpoint hooks install --harness grok --level project ``` System-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. Omit `--system` for the default non-root local install. GitHub Copilot CLI and Factory Droid OTLP use launch-environment settings rather than Beacon-managed shell-profile edits. ## Running user and system mode together A user-mode collector can run beside a system-mode one on the same machine when the two use different ports. Give the user install its own OTLP ports; its health-check port moves with them: ```bash title="Install a user-mode endpoint beside the system one" theme={null} beacon endpoint install --user --otlp-grpc-port 4327 --otlp-http-port 4328 ``` That collector listens on `127.0.0.1:4327`, `127.0.0.1:4328`, and health check `127.0.0.1:13143`. Pass `--health-port` to choose the health-check port yourself. The port is recorded as `collector.health_port` in `config.json`, and `beacon endpoint status` checks the recorded port. A config written before the field existed has no `health_port` and keeps using `13133`. If a port the collector needs is already taken, the install stops before it writes anything and names that port. If the collector starts but exits before it is ready, the install error quotes the collector's last error line and gives the path of its log, then rolls back. ## Related Inspect collector health, runtime log state, harnesses, diagnostics, and forwarding readiness. Install hook-based telemetry after the endpoint collector is configured. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.