Skip to main content

​
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.
Command syntax
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. 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 a real user’s agent runtime points at the collector (system mode only)
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.

​
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:
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.

​
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. 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

​
Examples

Run health checks with the default per-user paths:
Run health checks with the default per-user paths
Run health checks and apply supported fixes:
Run health checks and apply supported fixes
Check a root-managed endpoint deployment:
Check a root-managed endpoint deployment
Repair supported root-managed findings:
Repair supported root-managed findings
Print machine-readable check results:
Print machine-readable check results
Print machine-readable results with applied and skipped fix details:
Print machine-readable results with applied and skipped fix details
Use the top-level alias:
Use the top-level alias

Endpoint status

Inspect collector, service, harness, diagnostics, and runtime-log state.

Endpoint inventory

Show configured, detected, and observed endpoint inventory.