beacon endpoint install

Install local Beacon endpoint telemetry configuration

beacon endpoint install

beacon endpoint install configures the local endpoint agent, writes the OpenTelemetry Collector configuration, installs the launchd service, configures selected AI runtime harnesses, and optionally adds a Splunk HEC collector destination.

beacon endpoint install

By default, Beacon configures Claude Code and Codex CLI telemetry and uses full content retention for local or customer-controlled runtime JSONL logs.

Examples

Install with the default per-user paths:

beacon endpoint install

Install without starting the launchd service:

beacon endpoint install --no-start

Configure only one harness:

beacon endpoint install --harness claude

Use redacted content retention:

beacon endpoint install --content-retention redacted

Use metadata-only content retention:

beacon endpoint install --content-retention metadata

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

sudo beacon endpoint install --system --harness claude,codex --content-retention full

Install with Splunk HEC export while preserving the local runtime log:

beacon endpoint install \
  --splunk-hec-endpoint https://splunk.example:8088/services/collector \
  --splunk-hec-token "$SPLUNK_HEC_TOKEN" \
  --splunk-index beacon

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
--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 launchd service
--content-retention <mode>	Content retention mode: metadata, redacted, or full. Defaults to full
--splunk-hec-endpoint <url>	Splunk HEC endpoint URL, such as https://splunk.example:8088/services/collector
--splunk-hec-token <token>	Splunk HEC token. Required when Splunk HEC forwarding is configured
--splunk-index <index>	Optional Splunk index
--splunk-source <source>	Optional Splunk source. Defaults to beacon-endpoint-agent
--splunk-sourcetype <type>	Optional Splunk sourcetype. Defaults to beacon:endpoint
--splunk-insecure-skip-verify	Skip Splunk HEC TLS certificate verification
--splunk-ca-file <path>	Optional CA certificate path for Splunk HEC TLS verification

Splunk HEC export is additive. Beacon still writes the local runtime.jsonl audit log while the collector sends logs, traces, and metrics to the configured HEC endpoint.

Paths

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

Production endpoint install is currently supported on macOS. Omit --system for the default non-root local install.

Related

beacon endpoint status

Check collector, service, harness, and diagnostic status.

beacon endpoint repair

Reapply endpoint service and telemetry configuration.