> ## Documentation Index > Fetch the complete documentation index at: https://docs.beacon.sh/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 configures Claude Code and Codex CLI telemetry for local or customer-controlled runtime JSONL logs. Gemini CLI and VS Code Copilot telemetry are opt-in with the `gemini` and `vscode` harnesses. Claude Code can also use optional hook telemetry for richer lifecycle, subagent, permission, and tool detail; install the endpoint agent first, then add Claude hooks with `beacon endpoint hooks install --harness claude`. 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. GitHub Copilot CLI and Factory Droid OTLP are managed through their launch environments, so Beacon validates their telemetry state but does not mutate shell profiles during install. ## 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 ` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `openclaw`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint install --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments | | `--otlp-grpc-port ` | Local OTLP gRPC port. Defaults to `4317` | | `--otlp-http-port ` | Local OTLP HTTP port. Defaults to `4318` | | `--collector ` | Path to a `beacon-otelcol` binary | | `--no-start` | Write files without starting the collector service | | `--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 | | `--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 | | `--connect` | After a successful install, connect this endpoint to Beacon managed ingest: opens the dashboard to approve the device and starts the Vector forwarder. Same as running [`beacon endpoint connect`](/cli/endpoint-connect) afterwards | ## Telemetry destination question On a first interactive install the [onboarding prompt](/cli/endpoint-onboarding) ends with one more question, where this machine's agent telemetry should go, as an arrow-key menu with three answers: | Answer | What happens | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Keep it on this machine (default) | Nothing is forwarded. Enter picks this, so forwarding is never a side effect. | | Forward to your own infrastructure | A SIEM, observability platform, or an S3/GCS bucket you own. The prompt prints the [log forwarding docs](/log-forwarding) and the pack commands; the install stays local until you set one up. | | Forward to Beacon Managed | Runs the [connect flow](/cli/endpoint-connect) after the install completes. A failed connect is reported with the retry command and never fails the install. | `--connect` is already the answer, so it skips the question. `BEACON_MANAGED_INGEST=0` hides the Beacon answer; the question is never shown non-interactively. The answer is stored in the local onboarding profile and never sent. Local and own-infrastructure answers are recorded at once and the question is not asked again. The Beacon answer is recorded only once the machine is connected, so if the install or the connection fails, the next interactive install asks again. ## 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 ``` Opt in Gemini CLI telemetry alongside the defaults: ```bash title="Opt in Gemini CLI telemetry alongside the defaults" theme={null} beacon endpoint install --harness claude,codex,gemini ``` 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 ``` Install Claude Code hooks at the user level: ```bash title="Install Claude Code hooks at the user level" theme={null} beacon endpoint hooks install --harness claude ``` 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 tha Beacon-managed shell-profile edits. ## Known limitations A user-mode collector cannot run beside a system-mode one on the same machine. The collector health-check port (`127.0.0.1:13133`) is fixed, so the second collector cannot bind it; the install fails with `Collector ports are not listening` and rolls back the endpoint files it wrote. Either write the user-mode files without starting the service (`beacon endpoint install --user --no-start`) or uninstall the system endpoint first (`sudo beacon endpoint uninstall --system`). Tracked as [GitHub issue #447](https://github.com/asymptote-labs/agent-beacon/issues/447). ## Related Inspect collector health, runtime log state, harnesses, diagnostics, and forwarding readiness. Install hook-based telemetry after the endpoint collector is configured.