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 doctor"
description: "Run local Beacon endpoint health checks"
---
## Command overview
`beacon endpoint doctor` runs local health checks for the Beacon endpoint agent and exits non-zero when any hard check fails. Add `--fix` to apply safe remediations for supported findings.
```bash title="Command syntax"
beacon endpoint doctor
```
Use doctor when rollout automation, support scripts, or an operator needs a pass/fail health signal. For a broader status view that includes collector readiness, service state, discovered harnesses, and last-event state, use [`beacon endpoint status`](/cli/endpoint-status).
`beacon doctor` is a top-level alias for `beacon endpoint doctor`.
## Checks
Doctor verifies:
- Endpoint configuration file
- Endpoint configuration validity
- Collector configuration file
- Runtime JSONL log path
- Runtime log permissions
- Service definition: launchd plist on macOS, systemd unit on Linux
- Configured harness telemetry and recent observed events
- Whether DeepSeek Harness can load the hook bridge its hooks depend on (`dsh_hook_bridge`)
- Whether DeepSeek Harness hooks are actually recording live events (`dsh_hook_capture`)
- Whether Beacon's git hooks ran out of time recently (`git_hook_budget`)
- Whether a real user's agent runtime points at the collector (system mode only)
- The system log's access mode, and in the restricted mode whether the collector is serving the ingest socket (`runtime_log_access`)
The runtime log itself can be missing before the first event is written. In that case, doctor reports a warning instead of a hard failure.
### `runtime_log_access`
System mode only. Reports whether the system log is shared or [restricted](/cli/endpoint-install#restricted-log-access), and in the restricted mode whether everything it depends on is in place.
| Evidence | Status | Meaning |
|---|---|---|
| `log_access_shared` | ok | Hooks append to the log directly; any local account can modify or read it |
| `log_access_restricted` | ok | Only the collector writes the log; root and the `beacon-log` group read it |
| `ingest_socket_missing` | fail | The collector is not serving `/var/run/beacon-agent/ingest.sock`, so hooks are spooling their events instead of recording them. Start or repair the collector |
| `ingest_socket_unresponsive` | fail | The socket is there but nothing answers on it, usually because the collector was killed and left it behind. Doctor sends an empty batch rather than only checking the file. Restart the collector |
| `ingest_log_mismatch` | fail | The collector behind the socket writes a different runtime log from the one in `config.json`, so hooks are spooling their events |
| `ingest_socket_untrusted` | fail | Something is at the socket path that root does not own, so hooks will not send to it |
| `log_access_marker_missing` | fail | `config.json` says restricted but the log is not marked, so the collector would widen it again. Run `sudo beacon endpoint repair --system` |
| `log_access_mismatch` | warn | The log is marked restricted but `config.json` says shared, so hooks cannot append |
| `ingest_spool_pending` | warn | Events from the account running doctor are waiting in its spool; they go to the collector with its next event |
In the restricted mode, `runtime_log_permissions` checks that the log and its directory are closed to other accounts instead of checking that hooks can append. On Windows it reads the ACL of the log directory and of everything directly in it, and reports `restricted_acl` when only SYSTEM, Administrators and the `beacon-log` group (read only) can reach them, or `restricted_log_too_open` naming each grant to anyone else. Run without `sudo` (or, on Windows, unelevated), doctor cannot open a restricted log, and says so rather than reporting a failure. On Windows the suggested repair is `beacon endpoint repair --system` from an elevated shell.
### `console_user_configured`
System-mode only, and worth understanding because it is the one failure that a completely healthy endpoint can still report.
A system endpoint runs as root, so it has to work out whose agent settings to configure, and the collector is useless if nothing exports to it. This check asks whether that happened:
```
console_user_configured: fail target=alice (alice has no agent runtime pointed at this
collector, so their sessions are not being captured)
action="sudo beacon endpoint user-config repair-installed --system"
```
Everything else can be green when this fails. The collector is running, the service is loaded, and the harness check passes, because `doctor --system` runs as root and sees the settings the install wrote for root. The person whose sessions matter is the one with nothing.
If no logged-in user can be identified at all, this reports a warning rather than a failure: an unattended host legitimately has nobody to configure, and that is not something an operator can act on.
### `dsh_hook_bridge`
This check runs only when DeepSeek Harness is detected and Beacon's hooks for it are installed. `dsh` does not ship the Claude Code hook bridge the hooks run through, and a mount it cannot load is skipped at boot with a warning, so an install can be complete on disk and record nothing. The check reports what Beacon found about the bridge:
```
dsh_hook_bridge: warn target=deepseek_harness (DeepSeek Harness hooks are installed but dsh cannot
load them: hook bridge cannot be loaded by dsh 0.2.2: dsh is 0.2.2 but
@deepseek-ai/dsh-hooks-claude-code is 0.2.1-rc.2 and @deepseek-ai/dsh-hook-protocol is 0.2.1-rc.2; ...)
action="run `dsh plugin --profile <profile> add @deepseek-ai/[email protected] @deepseek-ai/[email protected]` (Beacon does not install packages), then restart dsh; ..."
```
| Evidence | Status | Meaning |
|----------|--------|---------|
| `dsh_hook_bridge_loads` | ok | A bridge and protocol matching `dsh` load, from a profile, the installation, or a path mount |
| `dsh_hook_bridge_partial` | warn | Some profiles have no bridge and boot without hooks; they are named |
| `dsh_hook_bridge_unavailable` | warn | Nothing loads a matching bridge, most often after a `dsh` upgrade (both versions are named), or a bridge mounted by path whose `dsh` peers do not resolve from where it sits |
| `dsh_version_unknown` | warn | A bridge resolves, but `dsh` is not on `PATH`, so its version cannot be compared |
It is a warning, not a failure: installing packages into a `dsh` profile is the operator's step, and Beacon does not take it. `--fix` lists the check as a manual skip. See [Installing the hook bridge](/runtimes/deepseek-harness#installing-the-hook-bridge).
### `dsh_hook_capture`
This check runs only when DeepSeek Harness is detected and Beacon's hooks for it are installed. It catches a failure no other check sees: the hooks are loaded, but they cannot write the runtime log because `dsh` runs them inside its session sandbox. In `workspace-write` the hook stages the event in the session workspace instead; in `read-only` nothing is writable and nothing is captured. `harness_observed` stays green in either state, because `beacon endpoint dsh sync` fills the log with poll events under the same harness name.
```
dsh_hook_capture: warn target=deepseek_harness (2 DeepSeek Harness session(s) ran without a live
hook event (newest 2026-09-21T11:00:00Z; no hook event since the hooks were installed). The usual
cause is dsh's sandbox: ...)
action="run `beacon endpoint dsh sync` to backfill those sessions from DeepSeek's session store; ..."
```
Sessions with staged events count differently. When a session's workspace spool still holds hook events, the check reports `dsh_spool_pending_drain` — capture is working, the sweep has not run — with the action `run beacon endpoint dsh sync`. Those sessions are not counted as missed, and once drained their events land as `harness.collection_method=hook` and satisfy the check like any other live capture.
```
dsh_spool_pending_drain: warn target=deepseek_harness (1 DeepSeek Harness session(s) have hook
events staged in their workspace spool; capture is working, but the events are not in
~/.beacon/endpoint/logs/runtime.jsonl yet)
action="run `beacon endpoint dsh sync` to drain the staged events into the runtime log"
```
Doctor cannot reproduce the sandbox, because running the hook command from doctor runs it outside `dsh`, where it succeeds. So the check compares evidence instead. It counts native sessions that DeepSeek wrote after the hooks were installed and more than a few minutes after the last event with `harness.collection_method=hook`. The live log and every rotated archive are searched for that event. Each of those sessions is one the live hooks did not capture. Once rotation has started discarding history, sessions older than the oldest retained event are not counted, because their hook events may have rotated out. Evidence doctor cannot read, such as a missing hooks file, is reported as a warning rather than a pass. The other cause is a `dsh` process that was already running when the hooks were installed and has not been restarted.
This is a warning, not a failure. The sandbox mode is the operator's choice in `dsh`, and Beacon does not change it. `--fix` lists the check as a manual skip. See [Live hooks and the DeepSeek Harness sandbox](/runtimes/deepseek-harness#live-hooks-and-the-deepseek-harness-sandbox).
### `git_hook_budget`
This check appears only when one of Beacon's [git hooks](/cli/git#hook-runs-that-run-out-of-time) ran out of time in the last seven days, in any repository. It counts the `git.hook_budget_exceeded` events in the runtime log and names the most recent.
```
git_hook_budget: warn target=/work/my-repo (2 hook run(s) ran out of time in the last 7 days, 1 cut short;
last 2026-10-14T09:00:03Z: post-commit in attribute, 3.3s of 3s, cut short)
action="run `beacon git status` in the repository to see its overruns, and `beacon git link <commit>` to link a commit the hook left unlinked"
```
It warns when a run was cut short, because a commit may have been left unlinked; runs that only finished late are reported as ok. The budgets are fixed, so `--fix` lists the check as a manual skip.
### `workspace_spool`
This check appears only when a [workspace spool](/cli/endpoint-spool) holds hook events: a sandboxed hook could not reach the socket or the runtime log, staged its events in the session workspace, and nothing has drained them yet. Capture is working; only the drain is missing.
```
workspace_spool: warn target=workspace_spool (2 session(s) have hook events staged in their workspace
spool; capture is working, but the events are not in ~/.beacon/endpoint/logs/runtime.jsonl yet)
action="run `beacon endpoint spool drain` as the user who owns the workspace"
```
| Evidence | Status | Meaning |
|----------|--------|---------|
| `workspace_spool_pending_drain` | warn (low) | Sessions Beacon has recorded, or sessions under `workspace_spool_roots`, have staged events waiting for a drain |
DeepSeek Harness sessions are left out: [`dsh_spool_pending_drain`](#dsh_hook_capture) already reports them.
## Fix mode
`beacon endpoint doctor --fix` plans and applies safe remediations for supported findings. It can create a missing runtime log, and recreate managed collector configuration and the service definition (a launchd plist or a systemd unit) when the endpoint configuration is valid. On a Windows system install it also resets the log directory ACL, from an elevated shell, when interactive users cannot append to the runtime log or when they hold more than append (an older install's Modify grant): the same ACL a fresh install applies, described in [Windows](/platforms/windows#what-the-install-does).
Fix mode deliberately skips cases that need operator intent, such as invalid endpoint configuration, missing harness setup, missing observed runtime events, unsafe runtime log permissions, or service repair on a host with no service manager to repair. If a collector service repair fails, Beacon rolls back the files and service state it changed where possible, then refreshes doctor results so the printed checks reflect any partial fixes that succeeded.
JSON output includes applied and skipped fix details so deployment scripts can distinguish remediated checks from findings that still need manual action.
## 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 |
| `--fix` | Apply safe remediations for supported failed or warning checks |
| `--json` | Print doctor results as JSON |
## Examples
Run health checks with the default per-user paths:
```bash title="Run health checks with the default per-user paths"
beacon endpoint doctor
```
Run health checks and apply supported fixes:
```bash title="Run health checks and apply supported fixes"
beacon endpoint doctor --fix
```
Check a root-managed endpoint deployment:
```bash title="Check a root-managed endpoint deployment"
sudo beacon endpoint doctor --system
```
Repair supported root-managed findings:
```bash title="Repair supported root-managed findings"
sudo beacon endpoint doctor --system --fix
```
Print machine-readable check results:
```bash title="Print machine-readable check results"
beacon endpoint doctor --json
```
Print machine-readable results with applied and skipped fix details:
```bash title="Print machine-readable results with applied and skipped fix details"
beacon endpoint doctor --fix --json
```
Use the top-level alias:
```bash title="Use the top-level alias"
beacon doctor
```
## Related
<Columns cols={2}>
<Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
Inspect collector, service, harness, diagnostics, and runtime-log state.
</Card>
<Card title="Endpoint inventory" icon="clipboard-list" href="/cli/endpoint-inventory">
Show configured, detected, and observed endpoint inventory.
</Card>
</Columns>