Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

31.8 KB
Raw Blame
---
title: "beacon endpoint install"
description: "Install or update the local Beacon endpoint collector and runtime telemetry"
---

## 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](/platforms/macos) or [Linux](/platforms/linux) for the platform setup, including the Linux packages and the `--service` flag.

```bash title="Command syntax"
beacon endpoint install
```

By default, Beacon discovers the runtimes installed for the invoking user and configures every integration it can safely install. This includes OTLP settings and supported hooks, plugins, or extensions; VS Code receives both its OTLP and hook configuration. An explicit `--harness` list disables automatic selection and configures only the runtimes it names: a hook-only list such as `--harness omp` leaves Claude Code's and Codex's settings untouched, and `--harness ""` installs the collector alone. If discovery finds no automatically installable runtime, Beacon installs the collector without changing any runtime configuration.

Discovery can also find runtimes whose collection path cannot be enabled safely by a machine-wide default. Beacon reports these without treating them as install failures: GitHub Copilot CLI needs launch-environment settings, Claude Cowork needs admin configuration, poll-only fx needs `beacon endpoint fx sync`, and OpenHands CLI/GUI coverage requires project-level hooks installed from inside each repository. Factory Droid's hooks are installed automatically when Droid is detected, while its separate OTLP endpoint remains launch-environment managed.

The `claude` harness writes both Claude Code's OpenTelemetry settings and its user-level hooks, because the OTLP export alone carries no session start or end, file activity, or subagent lifecycle; `beacon endpoint hooks uninstall --harness claude` removes the hooks again, and `beacon endpoint hooks install --harness claude --level project` adds project-level ones. A hook that cannot be written, for example into a settings file whose `hooks` key is not an object, is reported as a warning with the retry command; the endpoint itself is installed and `endpoint install` still exits 0. 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.

## 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 <selection>` | Harnesses to configure. Defaults to `auto`, which installs every detected integration Beacon can configure and reports detected manual or poll-only integrations. 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. An explicit list preserves exact-selection behavior |
| `--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 |
| `--no-browser` | During interactive setup, print the sign-in URL instead of opening a browser, and do not open the hosted dashboard when setup finishes. Useful where no browser can be opened. Open the URL on this machine, or on another computer after forwarding the port it names over SSH |
| `--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`. Turns on Claude Code's API-body logs; the collector keeps only that context and drops every body. Off by default; an install without the flag turns it 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](#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 |
| `--log-access <mode>` | System log access: `shared` (the default) or `restricted`. See [Restricted log access](#restricted-log-access). Omitted, an install keeps the mode the endpoint already has. A first install from a package is restricted ([Package installs](/security/restricted-log-access#package-installs)). System installs only |
| `--log-readers <accounts>` | Accounts to add to the `beacon-log` group of a restricted log, comma-separated (`DOMAIN\name` on Windows). Accounts are only added, never removed; one that cannot be added is reported without failing the install. Package installs set it from `BEACON_LOG_READERS`. System installs only |
| `--dashboard <mode>` | `enabled` (the default) or `disabled`: whether any account on this machine may run the [local dashboard](/cli/dashboard). See [Local dashboard](#local-dashboard). Omitted, an install keeps the recorded setting. System installs only |
| `--no-backfill` | Skip the [session backfill](#session-backfill). `BEACON_BACKFILL=0` does the same |
| `--connect` | After a successful install, attempt to connect this endpoint to Beacon Cloud ingest. User mode uses the signed-in CLI account; system mode opens browser approval. A connection failure does not roll back or fail the completed local install; verify with `beacon endpoint status --json` and retry with [`beacon endpoint connect`](/cli/endpoint-connect) |

## Session backfill

After a successful install, user or system mode, Beacon reads the last 30 days of agent sessions from each
runtime's own session store into the runtime log, so the [local dashboard](/cli/dashboard) has
your recent sessions before any agent runs again. It is the same sweep each runtime's sync command
runs (`beacon endpoint claude sync`, `codex sync`, `cursor sync`, `opencode sync`, `copilot sync`,
`cline sync`, `factory sync`, `pi sync`, `prime sync`, `hermes sync`, `devin sync`, `dsh sync`,
`fx sync`, `grok sync`, `antigravity sync`, `harness2 sync`, and `integrations openclaw sessions sync`), and its events carry
`harness.collection_method=poll` like theirs. It is local only and never touches the network.

The backfill is bounded so a machine with a lot of history cannot crowd live telemetry out of the
runtime log's rotation window:

- Only sessions modified in the last 30 days are read, newest first.
- It writes at most 24 MiB in total, and no single runtime takes more than 12 MiB of that.

Nothing past a limit is lost. The collector cursors move only past what was written, and sessions
left out are not touched, so the runtime's sync command reads the rest; install names the command
for each runtime that hit the limit. A runtime also stops early, and is reported the same way,
if writing more would rotate its own backfill out of the log, which takes heavy live activity
during the backfill. A runtime whose store cannot be read is reported as a warning
and never fails the install. Re-running install reads only what changed since the last sweep.

A system, package or MDM install runs as root, whose home holds no agent sessions, so it reads the
session stores of the active console user instead: the same person system hook repair and the
scheduled inventory resolve (`SUDO_USER` or the logind seat on Linux, the console owner on macOS,
the active session on Windows). Its collector cursors stay under the system base directory. Because
root is reading a home that user controls, the read is confined to that home: a link that leads out
of it, a file the user does not own (including a hard link to someone else's), and a FIFO, socket or
device are skipped rather than read, and install lists what it skipped. SQLite stores are read from
a private copy under the system base directory, retaken if the runtime rewrites its write-ahead log
mid-copy; a database larger than 512 MiB with its log is not copied, and install names the
runtime's sync command to run as the user instead. A manual `beacon endpoint <runtime> sync` run as the user is not confined. When
nobody is logged in, install says the backfill was skipped and the next connect or manual sync
reads the sessions. `--dry-run` installs skip it, and `--no-backfill` or `BEACON_BACKFILL=0` turn it
off. If this install also connects to Beacon Cloud, the same history is
[uploaded by the connect](/cli/endpoint-connect#session-backfill).

## Scheduled session sync

The session backfill runs once, at install. To keep reading the runtimes' session stores after that, turn on the scheduled session sync:

```bash
sudo beacon endpoint sessions enable --system   # an endpoint that is already installed
sudo beacon endpoint sessions disable --system  # turn it off and remove the job
```

`sessions enable` and `disable` change only this setting and the job. `install` and `repair` take `--session-sync` and `--no-session-sync` too, but repair rebuilds the endpoint from its flags: run without the ones the endpoint was set up with, it resets the harnesses and OTLP ports and drops a Splunk or Falcon HEC destination. For a package or MDM rollout, set `BEACON_SESSION_SYNC=1` in the environment of the package's install script (`/opt/beacon/scripts/install-endpoint.sh`), or run `/opt/beacon/bin/beacon endpoint sessions enable --system` on Macs that already have Beacon. `BEACON_SESSION_SYNC=0` turns it off, and leaving it unset keeps what the endpoint already has, so a package upgrade never changes it.

It is off by default. Hooks and OTLP already capture sessions live, and the session stores add what only they record, such as Claude Code's per-request token usage and complete assistant text from its transcripts. Turning it on writes those records as poll events (`harness.collection_method=poll`) alongside the live ones, which matters when the runtime log is forwarded elsewhere. Token reports keep live usage authoritative over poll usage for the same session.

### How it runs

- The job runs `beacon endpoint sessions sync` every 15 minutes: `com.beacon.endpoint.session-sync` (a LaunchDaemon in system mode, a LaunchAgent in user mode) or `beacon-session-sync.timer` on systemd. The first run is 15 minutes after the job is loaded by the install, a repair, a reboot or a package upgrade, never at load.
- Each run is the same sweep as the backfill above, with the same 30-day window, size budget and, in system mode, the same confined read of the console user's stores. Each runtime's cursor makes a run read only what is new. With nobody logged in, a system run reads nothing.
- In system mode a SQLite store (Cursor, OpenCode, Devin CLI, Hermes Agent) is read from a private copy, as the backfill does. A copy can approach 512 MiB and those runtimes are captured live by their hooks or plugins, so the scheduled job copies each one at most once an hour. A store over 512 MiB is skipped and named in the job's output; run that runtime's sync command as the user to read it.
- Only one sync runs at a time. An install, connect, `beacon endpoint sessions sync` or `beacon endpoint <runtime> sync` waits for a sync already in progress and then reads only what it left. A scheduled run or a `--watch` sweep skips its turn while another sync is running, and `--print` dry runs never wait.
- When the install or a later connect skipped the backfill (`--no-backfill` or `BEACON_BACKFILL=0`), each runtime no sync had read yet is limited to sessions active since that skip, not the last 30 days. A session that continues past the skip is read from its start, a runtime that was already synced reads on from where it was, and a later backfill lifts the limit.
- A user-mode job keeps the store locations the install saw (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `XDG_DATA_HOME`, `OPENCODE_DB` and the rest), because the scheduler does not pass a shell's environment.

### What to expect when you turn it on

The first runs catch up. When the backfill stopped at its size limit, the rest of the last 30 days is left for the job, and each run writes up to another 12 MiB per runtime (24 MiB in all) until it has read everything. After that, a run writes only what the agents recorded since the previous one. On a machine with a lot of agent history the catch-up takes a few runs, and because the runtime log rotates at 10 MiB and keeps five archives, it pushes older local events out of the log sooner than live telemetry alone would. A connected endpoint forwards the catch-up like any other new events.

### Settings and status

The setting is `session_sync.enabled` in `config.json`. Repair and package upgrades keep it, and `beacon endpoint sessions disable` or `--no-session-sync` turns it off and removes the job. A scheduled run also checks the setting, so a job left behind after the config was set to off reads nothing. `beacon endpoint status` shows `Session sync: every 15m0s; job loaded=true`, and `beacon endpoint sessions sync` runs the same sweep by hand. A host without launchd or systemd cannot run the job; run `beacon endpoint sessions sync` from your own scheduler there.

## Interactive onboarding wizard

On a first interactive install the [onboarding wizard](/cli/endpoint-onboarding)
signs in through beacon.sh, then asks where this machine's telemetry should go:

| Answer | What happens |
|--------|--------------|
| Beacon Cloud (default) | Shows what will be sent, asks for Standard or Metadata-only capture, then installs Beacon and connects this endpoint. The confirm screen names the signed-in account and states that forwarding starts, then names the operator, the destination, and the capture mode, and says how to turn off research and AI training, change the mode, stop sending, or delete the data. It also says that the last 30 days of agent sessions are uploaded, before you accept. Once connected, the install ends on a [short summary](/cli/endpoint-onboarding#when-setup-finishes) and opens the hosted dashboard. An endpoint that is already enrolled keeps its device key and is not re-enrolled. |
| Local only | Explicitly opts out of managed forwarding. Nothing is sent anywhere; the session backfill stays in the local log. |

`--connect` presets Beacon Cloud and skips the destination question. Whether
connect was chosen in the wizard or by the flag, a failed enrollment leaves the
completed local install exiting successfully and prints `beacon endpoint connect` as
the retry command. Automation should verify
`.managed_ingest.connected` with `beacon endpoint status --json`.
`BEACON_MANAGED_INGEST=0` hides the managed answer. The wizard is never shown
for system/root, package, MDM, CI, dry-run, or redirected-input installs.
Customer-managed destinations remain available through the
[log forwarding packs](/log-forwarding) after choosing Local.

## Examples

Install with the default per-user paths:

```bash title="Install with the default per-user paths"
beacon endpoint install
```

Install without starting the collector service:

```bash title="Install without starting the collector service"
beacon endpoint install --no-start
```

Configure only one harness:

```bash title="Configure only one harness"
beacon endpoint install --harness claude
```

Override discovery with an exact harness list:

```bash title="Configure an exact harness list"
beacon endpoint install --harness claude,codex,gemini
```

Force every installable integration without checking whether its runtime is present:

```bash title="Configure all supported integrations"
beacon endpoint install --harness all
```

Configure VS Code Copilot telemetry:

```bash title="Configure VS Code Copilot telemetry"
beacon endpoint install --harness vscode
```

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

```bash title="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:

```bash title="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:

```bash title="Include raw Codex spans for troubleshooting"
beacon endpoint install --include-codex-spans
```

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

```bash title="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:

```bash title="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:

```bash title="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:

```bash title="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:

```bash title="Install runtime hooks"
beacon endpoint hooks install --harness antigravity,claude,cline,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen
```

Claude Code hooks are already installed at the user level by `endpoint install`. Add project-level hooks, or re-add user-level ones after removing them:

```bash title="Add Claude Code hooks to a project"
beacon endpoint hooks install --harness claude --level project
```

Install Grok Build hooks at the user level:

```bash title="Install Grok Build hooks at the user level"
beacon endpoint hooks install --harness grok
```

Install Hermes Agent hooks at the user level:

```bash title="Install Hermes Agent hooks at the user level"
beacon endpoint hooks install --harness hermes
```

Hermes hooks write `config.yaml` in the Hermes home directory, which follows `HERMES_HOME` and the active profile (default `~/.hermes/config.yaml`; see [Hermes home and profiles](/runtimes/hermes-agent#hermes-home-and-profiles)), and support user-level installs only.

Install Qwen Code hooks at the user level:

```bash title="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:

```bash title="Install project-level Grok Build hooks"
beacon endpoint hooks install --harness grok --level project
```

<Note>
  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.
</Note>

## Restricted log access

A system-mode endpoint keeps one runtime log, `/var/log/beacon-agent/runtime.jsonl`, for every user on the machine. By default the log is shared: hooks run as each logged-in user and append to it directly, so the file is `0666`. That also means any local account can truncate or rewrite the log, and read every other user's prompts, command output and diffs.

`--log-access restricted` makes the collector the only writer:

```bash title="Install with restricted log access"
sudo beacon endpoint install --system --log-access restricted
```

- Hooks send their events to the collector over a local Unix socket, `/var/run/beacon-agent/ingest.sock`, instead of writing the file. Nothing leaves the machine.
- The collector records each event under the account the operating system says sent it, not the account the event claims.
- The log directory becomes `root:beacon-log` mode `2750`, the log and its archives `0640`, and its lock `0600`. Only the collector writes the log; only root and members of the `beacon-log` group read it. Switching an existing log to restricted replaces its files with fresh copies, so a handle another account opened while the log was shared stops reaching it.
- If the collector is stopped or restarting, hooks keep their events in a private spool in each user's home (`~/.beacon/endpoint/spool`, `0600`) and send them with the next event once the collector is back. The agent is never held up.

Install creates the `beacon-log` group when it is missing and adds nobody to it. Add each account that should read the log, such as a log shipper's service account, then restart that shipper:

```bash title="Let a log shipper read a restricted log"
# Linux
sudo usermod -aG beacon-log <account>
# macOS
sudo dseditgroup -o edit -a <account> -t user beacon-log
```

The log format and every event field stay the same, so a SIEM or forwarder that parses the log needs no change. Shippers that run as root, and the Beacon Cloud forwarder, keep working without one.

The mode is recorded in `config.json` as `log_access`, and in a root-owned `.beacon-log-access` marker beside the log. `beacon endpoint repair`, package upgrades, the Jamf `repair-hooks.sh` policy, and a reinstall after `uninstall --keep-logs` keep it. To go back, run `sudo beacon endpoint repair --system --log-access shared`; the log is writable by every account again at once. A first install from a package (the `.deb` or `.rpm`, the macOS `.pkg`, the Windows MSI) is restricted without any setting, and adds to `beacon-log` only the person who ran it interactively, or the accounts in `BEACON_LOG_READERS`; `BEACON_LOG_ACCESS=shared` opts out. Fleet tooling that cannot set the install script's environment sets these in `/etc/default/beacon` on Linux, managed preferences on macOS, or registry policy on Windows; see [Package installs](/security/restricted-log-access#package-installs).

What this does and does not change:

- Local accounts can no longer alter or delete events already in the log, or read other users' sessions.
- Every event that arrives over the socket records the account that sent it, as the operating system reports it. A user still controls their own agent, so they can still send events of their own choosing, including ones that name another session's id, but always under their own account.
- The collector's OTLP ports on `127.0.0.1` still accept telemetry from any local process, as they do in the shared mode. Agents that export over OTLP, such as Claude Code and Codex, and the browser extension use them. Events that arrive that way are recorded under the account that owns the sending connection, as the operating system reports it, in either mode and on Linux, macOS and Windows (with no `user` when the sender disconnected before the collector could look). That names the sender; it does not stop an account sending whatever it likes under its own name.

While the endpoint is restricted, commands that read the system log as the person running them (`beacon endpoint dashboard`, `beacon scan`, `beacon traces`, and the session lookups in `beacon share`, `beacon handoff` and `beacon git` commit linking) see it only when run as root or by a `beacon-log` member. [`beacon endpoint doctor`](/cli/endpoint-doctor#runtime_log_access) connects to the socket and reports a collector that is not answering on it, including one that was killed and left its socket behind, and any events waiting in the caller's spool. On Windows the mode works the same way with Windows mechanisms: hooks send to the named pipe `\\.\pipe\beacon-agent-ingest`, the log directory's ACL gives SYSTEM and Administrators full control, the `beacon-log` local group read and nobody else anything, events record the sender's SID and account name, and the commands run from an elevated shell (see [On Windows](/security/restricted-log-access#on-windows)). For how the mode fits with log shippers such as Microsoft Sentinel, and what it does and does not protect, see [Restricted log access](/security/restricted-log-access).

## Local dashboard

[`beacon endpoint dashboard`](/cli/dashboard) runs only while someone runs it, binds to loopback,
and serves only the browser that opened the secret URL it printed
([access control](/cli/dashboard#access-control)). An administrator who does not want it run at
all can turn it off for every account, root included:

```bash title="Turn the local dashboard off on this machine"
sudo beacon endpoint install --system --dashboard disabled
```

The setting is recorded in the system `config.json` as `"dashboard": "disabled"` and kept by
`beacon endpoint repair`, package upgrades and reinstalls until `--dashboard enabled` turns it back
on. While it is off, `beacon endpoint dashboard` and `beacon lenses preview` refuse to start for
everyone, including a user-mode run on the same machine. The check needs no privileges. Once the
system config holds a Splunk or Falcon HEC token it is readable only by root (SYSTEM and
Administrators on Windows), so install and repair also keep a `dashboard-disabled` file beside it
while the dashboard is off, which every account can read; an account that cannot read
`config.json` goes by that file. Any value other than `enabled` (or none) reads as disabled, and a
system config that does not parse refuses too, so a damaged or mistyped setting never turns the
dashboard back on. If you edit `config.json` by hand, run `beacon endpoint repair --system` so the
file beside it follows.
`beacon endpoint status` prints `Dashboard: enabled` or `Dashboard: disabled by the administrator`
(`dashboard` in `--json`). `--dashboard` is refused in user mode, whose config would switch nothing off.

For package installs, set `BEACON_DASHBOARD=enabled` or `BEACON_DASHBOARD=disabled` in the
environment of the package's install script (`install-endpoint.sh` on macOS and Linux,
`install-endpoint.ps1` on Windows). Unset, an unattended first package install (no system config or
log on the machine, and no person installing it, by the same test that decides who is added to
`beacon-log`) turns the dashboard off; a person's own install keeps it, and an upgrade or a reinstall
over a kept config or log keeps the endpoint's setting. Fleet tooling can set it
where it writes the other install settings (`/etc/default/beacon` or `/etc/sysconfig/beacon`, the
`com.beacon.endpoint` managed preferences, or the `HKLM\SOFTWARE\Policies\Beacon\Endpoint` policy key);
see [Package installs](/security/restricted-log-access#package-installs).

## Running user and system mode together

A user-mode collector can run beside a system-mode one on the same machine when the two use different ports. Give the user install its own OTLP ports; its health-check port moves with them:

```bash title="Install a user-mode endpoint beside the system one"
beacon endpoint install --user --otlp-grpc-port 4327 --otlp-http-port 4328
```

That collector listens on `127.0.0.1:4327`, `127.0.0.1:4328`, and health check `127.0.0.1:13143`. Pass `--health-port` to choose the health-check port yourself. The port is recorded as `collector.health_port` in `config.json`, and `beacon endpoint status` checks the recorded port. A config written before the field existed has no `health_port` and keeps using `13133`.

If a port the collector needs is already taken, the install stops before it writes anything and names that port. If the collector starts but exits before it is ready, the install error quotes the collector's last error line and gives the path of its log, then rolls back.

## Related

<Columns cols={2}>
  <Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
    Inspect collector health, runtime log state, harnesses, diagnostics, and forwarding readiness.
  </Card>
  <Card title="Runtime hooks" icon="plug" href="/cli/hooks">
    Install hook-based telemetry after the endpoint collector is configured.
  </Card>
</Columns>