The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "beacon endpoint repair"
description: "Repair Beacon endpoint service files, collector configuration, and telemetry settings"
---
## Command overview
`beacon endpoint repair` reapplies Beacon endpoint service files, collector configuration, harness telemetry configuration, and optional destinations such as Splunk HEC or Falcon LogScale HEC. It is useful after upgrading Beacon, changing ports, changing SIEM settings, or correcting local configuration drift.
```bash title="Command syntax"
beacon endpoint repair
```
Repair preserves runtime logs while reinstalling managed endpoint files. By default it rediscovers installed runtimes and reapplies every integration Beacon can configure. Pass an explicit `--harness` list to repair only those targets; runtimes it does not name, including Claude Code and Codex, are not written. GitHub Copilot CLI and Factory Droid launch-environment settings remain customer-managed; repair does not write those environment settings.
During repair, Beacon removes the existing managed service before reinstalling it so an unhealthy collector can release local OTLP ports. If reinstall cannot complete, Beacon restores the previous endpoint configuration so local state is not left partially rolled back.
On an endpoint connected to Beacon Cloud, repair leaves the forwarder service, the device key, and Vector's checkpoints and buffer in place, and re-renders `vector.toml` from this version's forwarder pack with the recorded ingest URL and privacy mode. Vector validates the new config before it replaces the old one; a running forwarder restarts so it reads the current runtime log, which switching to restricted log access replaces with a copy, and a config Vector rejects is reported as a warning while the forwarder keeps running on the old one. Repair never re-enrolls the device or rotates its key, and `--no-start` leaves the forwarder untouched. See [Keeping the forwarder config current](/cli/endpoint-connect#keeping-the-forwarder-config-current).
## Flags
| Flag | Description |
|------|-------------|
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and launch daemon |
| `--log-path <path>` | Runtime JSONL log path |
| `--harness <selection>` | Harnesses to configure. Defaults to `auto`, which repairs every detected integration Beacon can configure. 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 |
| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` |
| `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` |
| `--health-port <port>` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that is changed (HTTP port `4328` gives `13143`), so a second collector on alternate OTLP ports does not collide with the first |
| `--collector <path>` | Path to a `beacon-otelcol` binary. Without it, Beacon uses the one beside the `beacon` CLI, then one on `PATH` |
| `--no-start` | Write files without starting the collector service |
| `--log-access <mode>` | Change the system log's access mode to `shared` or `restricted`. Omitted, repair keeps the current mode. See [Restricted log access](/cli/endpoint-install#restricted-log-access) |
| `--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 |
| `--claude-capture-model-context` | Record context Claude Code gives the model that no other event reports: the pages its WebFetch tool fetches, and the MCP tool descriptions it shows the model as `mcp.tool_listed`. Pass it on every repair that should keep capture on; a repair without it turns capture off. See [Claude Code: model context from API bodies](/runtimes/claude-code#model-context-from-api-bodies) |
| `--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 |
| `--otlp-forward-endpoint <endpoint>` | Also forward the Claude Code and Codex OTLP the local collector receives, with secrets redacted and raw API bodies dropped, to a second OTLP endpoint: `host:port` or a URL for gRPC, the base URL for HTTP. For runtimes that already exported to another backend before Beacon took over their OTLP settings. See [Kandji, GCS and an existing OTLP backend](/guides/kandji-otlp-forward-mdm). Omitted, install and repair keep the forward the endpoint already has |
| `--otlp-forward-protocol <protocol>` | `grpc` (default) or `http/protobuf` |
| `--otlp-forward-harness <list>` | Runtimes whose OTLP the forward carries, comma-separated. Default `claude,codex`; any other source, such as the browser extension, stays local |
| `--otlp-forward-header <name=value>` | Header sent with every forwarded export, usually the backend's API key; repeatable. Values are stored in a root-only `otlp-forward-headers.json` beside `config.json`, which keeps only the names; status and doctor show names only |
| `--otlp-forward-insecure` | Send the forward without TLS (plaintext gRPC) |
| `--otlp-forward-insecure-skip-verify` | Skip TLS certificate verification for the forward |
| `--otlp-forward-ca-file <path>` | Optional CA certificate path for the forward's TLS verification |
| `--no-otlp-forward` | Remove a configured OTLP forward |
| `--session-sync` | Turn on the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync): every 15 minutes, read new records from the agent runtimes' local session stores into the runtime log. Kept by repair and package upgrades |
| `--no-session-sync` | Turn the scheduled session sync off and remove its job |
## Examples
Repair a default per-user install:
```bash title="Repair a default per-user install"
beacon endpoint repair
```
Repair and opt into low-level runtime OTLP metrics:
```bash title="Repair and opt into low-level runtime OTLP metrics"
beacon endpoint repair --include-runtime-metrics
```
Repair after changing Copilot CLI's customer-managed launch environment:
```bash title="Repair after changing Copilot CLI's customer-managed launch environment"
export COPILOT_OTEL_ENABLED="true"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
beacon endpoint repair
```
Repair and opt into raw Codex spans for troubleshooting:
```bash title="Repair and opt into raw Codex spans for troubleshooting"
beacon endpoint repair --include-codex-spans
```
Repair and configure Devin CLI and Devin Desktop hooks:
```bash title="Repair and configure Devin CLI and Devin Desktop hooks"
beacon endpoint repair --harness claude,codex,devin-cli,devin-desktop
```
Repair with custom OTLP ports:
```bash title="Repair with custom OTLP ports"
beacon endpoint repair --otlp-grpc-port 14317 --otlp-http-port 14318
```
Repair a system-mode deployment:
```bash title="Repair a system-mode deployment"
sudo beacon endpoint repair --system
```
Repair and add or update Splunk HEC export:
```bash title="Repair and add or update Splunk HEC export"
beacon endpoint repair \
--splunk-hec-endpoint https://splunk.example:8088/services/collector \
--splunk-hec-token "$SPLUNK_HEC_TOKEN" \
--splunk-index beacon
```
Repair and add or update Falcon LogScale HEC export:
```bash title="Repair and add or update Falcon LogScale HEC export"
beacon endpoint repair \
--falcon-hec-endpoint https://cloud.<region>.humio.com/api/v1/ingest/hec \
--falcon-hec-token "$FALCON_HEC_TOKEN" \
--falcon-index beacon
```
## Related
<Columns cols={2}>
<Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
Check collector health and runtime telemetry state after repair.
</Card>
<Card title="Endpoint install" icon="download" href="/cli/endpoint-install">
Review install options and endpoint configuration defaults.
</Card>
</Columns>