beacon endpoint install

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 or Linux for the platform setup, including the Linux packages and the --service flag.

Command syntax

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 <path>`	Runtime JSONL log path
`--harness <list>`	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 <port>`	Local OTLP gRPC port. Defaults to `4317`
`--otlp-http-port <port>`	Local OTLP HTTP port. Defaults to `4318`
`--collector <path>`	Path to a `beacon-otelcol` binary
`--no-start`	Write files without starting the collector service
`--service <kind>`	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 <url>`	Splunk HEC endpoint URL
`--splunk-hec-token <token>`	Splunk HEC token
`--splunk-index <index>`	Optional Splunk index
`--splunk-source <source>`	Optional Splunk source
`--splunk-sourcetype <type>`	Optional Splunk sourcetype
`--splunk-insecure-skip-verify`	Skip Splunk HEC TLS certificate verification
`--splunk-ca-file <path>`	Optional CA certificate path for Splunk HEC TLS verification
`--falcon-hec-endpoint <url>`	Falcon LogScale HEC endpoint URL
`--falcon-hec-token <token>`	Falcon LogScale ingest token
`--falcon-index <repository>`	Optional Falcon LogScale repository for multi-repository tokens
`--falcon-source <source>`	Optional Falcon LogScale source
`--falcon-sourcetype <type>`	Optional Falcon LogScale parser or sourcetype
`--falcon-insecure-skip-verify`	Skip Falcon LogScale HEC TLS certificate verification
`--falcon-ca-file <path>`	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` afterwards

Telemetry destination question

On a first interactive install the onboarding prompt 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 and the pack commands; the install stays local until you set one up.
Forward to Beacon Managed	Runs the connect flow 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:

Install with the default per-user paths

beacon endpoint install

Install without starting the collector service:

Install without starting the collector service

beacon endpoint install --no-start

Configure only one harness:

Configure only one harness

beacon endpoint install --harness claude

Opt in Gemini CLI telemetry alongside the defaults:

Opt in Gemini CLI telemetry alongside the defaults

beacon endpoint install --harness claude,codex,gemini

Configure VS Code Copilot telemetry:

Configure VS Code Copilot telemetry

beacon endpoint install --harness vscode

Configure Devin CLI and Devin Desktop hooks alongside the default OTLP harnesses:

Configure Devin CLI and Devin Desktop hooks alongside the default OTLP harnesses

beacon endpoint install --harness claude,codex,devin-cli,devin-desktop

Include low-level runtime OTLP metrics that are filtered from JSONL by default:

Include low-level runtime OTLP metrics that are filtered from JSONL by default

beacon endpoint install --include-runtime-metrics

Include raw Codex spans for troubleshooting:

Include raw Codex spans for troubleshooting

beacon endpoint install --include-codex-spans

Install with system paths for a root-managed package or MDM deployment:

Install with system paths for a root-managed package or MDM deployment

sudo beacon endpoint install --system --harness claude,codex

Install and forward to CrowdStrike Falcon LogScale HEC:

Install and forward to CrowdStrike Falcon LogScale HEC

sudo beacon endpoint install \
  --system \
  --falcon-hec-endpoint https://cloud.<region>.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:

Configure Factory Droid's OTLP endpoint through MDM or another customer-owned launch policy

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:

Configure GitHub Copilot CLI's OTLP endpoint through MDM or another customer-owned launch policy

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:

Install runtime hooks

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:

Install Claude Code hooks at the user level

beacon endpoint hooks install --harness claude

Install Grok Build hooks at the user level:

Install Grok Build hooks at the user level

beacon endpoint hooks install --harness grok

Install Hermes Agent hooks at the user level:

Install Hermes Agent hooks at the user level

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:

Install Qwen Code hooks at the user level

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:

Install project-level Grok Build hooks

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.

Endpoint status

Inspect collector health, runtime log state, harnesses, diagnostics, and forwarding readiness.

Runtime hooks

Install hook-based telemetry after the endpoint collector is configured.

Install and Upgrade

CLI Resources

Command Manual

beacon endpoint install

Command overview

Flags

Telemetry destination question

Examples

Known limitations

Endpoint status

Runtime hooks

​Command overview

​Flags

​Telemetry destination question

​Examples

​Known limitations

​Related

Endpoint status

Runtime hooks

Command overview

Flags

Telemetry destination question

Examples

Known limitations

Related