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
docs: document installing and running Beacon on Linux
shukieshahb6c98152c3f8
diff --git a/README.md b/README.mdindex 85eaaaf6..cbded19c 100644--- a/README.md+++ b/README.md@@ -162,8 +162,14 @@ Agent Beacon is designed for Security and IT teams to deploy and validatethrough standard MDM workflows.Version tags publish a signed, notarized, and stapled Apple Silicon endpoint-`.pkg` to GitHub Releases for MDM/manual download. Homebrew and release archives-remain available for CLI installs across supported macOS/Linux architectures.+`.pkg` to GitHub Releases for MDM/manual download, along with `.deb` and `.rpm`+packages for Linux on amd64 and arm64. Homebrew and release archives remain+available for CLI installs across supported macOS/Linux architectures.++Installing a Linux package performs the system-mode install itself: it registers+and starts a systemd unit, writes configuration to `/etc/beacon/endpoint`, and+points the installing user's agent runtimes at the local collector. See the+[Linux install guide](https://docs.asymptotelabs.ai/cli/endpoint-linux).| MDM platform | Support path || --- | --- |diff --git a/docs/cli/endpoint-doctor.mdx b/docs/cli/endpoint-doctor.mdxindex 80753e80..97015ef9 100644--- a/docs/cli/endpoint-doctor.mdx+++ b/docs/cli/endpoint-doctor.mdx@@ -24,16 +24,16 @@ Doctor verifies:- Collector configuration file- Runtime JSONL log path- Runtime log permissions-- launchd plist on macOS+- Service definition: launchd plist on macOS, systemd unit on Linux- Configured harness telemetry and recent observed eventsThe runtime log itself can be missing before the first event is written. In that case, doctor reports a warning instead of a hard failure.## Fix mode-`beacon endpoint doctor --fix` plans and applies safe remediations for supported findings. It can create a missing runtime log and, on macOS, recreate managed collector configuration and launchd service files when the endpoint configuration is valid.+`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 non-macOS service 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.+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.diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 8a7fb1a7..197166f5 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -5,7 +5,9 @@ description: "Install or update the local Beacon endpoint collector and runtime## Command Overview-`beacon endpoint install` configures the local endpoint agent, writes the OpenTelemetry Collector configuration, installs the launchd service, configures selected agent harnesses, and optionally adds Splunk HEC or Falcon LogScale HEC collector destinations.+`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 [Linux install](/cli/endpoint-linux) for the Linux packages and the `--service` flag.```bash title="Command syntax"beacon endpoint install@@ -24,7 +26,7 @@ By default, Beacon configures Claude Code and Codex CLI telemetry for local or c| `--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 |+| `--no-start` | Write files without starting the collector service || `--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 high-volume Codex OTLP spans for troubleshooting. By default, Beacon records Codex semantic logs and suppresses raw Codex spans || `--splunk-hec-endpoint <url>` | Splunk HEC endpoint URL |@@ -50,9 +52,9 @@ Install with the default per-user paths:beacon endpoint install```-Install without starting the launchd service:+Install without starting the collector service:-```bash title="Install without starting the launchd service"+```bash title="Install without starting the collector service"beacon endpoint install --no-start```@@ -155,7 +157,7 @@ beacon endpoint hooks install --harness grok --level project```<Note>- Production endpoint install is currently supported on macOS. Omit `--system` for the default non-root local install. GitHub Copilot CLI and Factory Droid OTLP use launch-environment settings rather than Beacon-managed shell-profile edits.+ 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 than Beacon-managed shell-profile edits.</Note>## Relateddiff --git a/docs/cli/endpoint-linux.mdx b/docs/cli/endpoint-linux.mdxnew file mode 100644index 00000000..adbbd89e--- /dev/null+++ b/docs/cli/endpoint-linux.mdx@@ -0,0 +1,203 @@+---+title: "Linux Install"+description: "Install the Beacon endpoint on Linux with a .deb or .rpm, and understand how the systemd service is managed"+---++Beacon runs a local collector on your machine, points your agent runtimes at it, and writes+normalized events to a JSONL log you own. On Linux the collector runs as a systemd service.++Installing the package is the whole setup. It unpacks the binaries, performs the system-mode+install, registers and starts the systemd unit, and configures the runtime of the user who ran the+install. There is no second command to run.++## Install++Download the package for your architecture from the+[latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:++<CodeGroup>+```bash title="Debian, Ubuntu"+sudo apt install ./beacon_<version>_linux_amd64.deb+```++```bash title="Fedora, RHEL, Rocky, Alma"+sudo dnf install ./beacon-<version>-linux-amd64.rpm+```+</CodeGroup>++`amd64` and `arm64` packages are published for both formats.++Then check it:++```bash title="Verify the install"+beacon endpoint status --system+beacon endpoint doctor --system+```++`status` should report the service as running with `kind: systemd`. `doctor` checks the whole chain —+unit, collector, config, log, harness settings — and prints the command to fix anything it finds.++<Note>+ The package depends on systemd, because the service it registers is a systemd unit. On a+ distribution without systemd, install the CLI from the tarball and run `beacon endpoint install`+ without `--system`; see [Without systemd](#without-systemd).+</Note>++## What the install does++| Step | Result |+|---|---|+| Unpack | `beacon`, `beacon-hooks` and `beacon-otelcol` under `/opt/beacon/bin` |+| System install | Config and collector config under `/etc/beacon/endpoint` |+| Service | `/etc/systemd/system/beacon-collector.service`, enabled and started |+| Runtime log | `/var/log/beacon-agent/runtime.jsonl` |+| Agent runtime | Claude Code and Codex CLI settings for the installing user, pointed at `127.0.0.1:4317` |++That last row is worth knowing about. A system-mode endpoint runs as root, so the install has to+work out *whose* agent settings to configure — the collector is useless if nothing is exporting to+it. Beacon uses `SUDO_USER`, which is set for every normal install path, and falls back to asking+logind who has an active session. If it cannot identify anyone, it says so instead of failing, and+you can configure yourself later:++```bash title="Configure your own agent runtime against an already-installed endpoint"+sudo beacon endpoint user-config repair-installed --system+```++Other users on the same machine run the same command for themselves. They all export to the same+collector and the same log, which is why `/var/log/beacon-agent/runtime.jsonl` is group- and+world-writable — hooks run as the logged-in user and append to it directly.++## Managing the service++The unit is an ordinary systemd service, so the usual commands work:++```bash title="Service management"+systemctl status beacon-collector+systemctl restart beacon-collector+journalctl -u beacon-collector -f+```++`Restart=always` means systemd brings the collector back if it exits, and `WantedBy=multi-user.target`+means it starts on boot. Both are set by the install; you do not need to configure them.++If the unit is missing or broken, repair it without reinstalling the package:++```bash title="Repair the service"+sudo beacon endpoint doctor --system --fix+```++## Choosing a service backend++Beacon decides which service manager to use by reading what is actually running as PID 1. It does+not check whether `systemctl` exists on `PATH` — inside a container that is often true while systemd+is not running at all, and trusting it would produce a unit nothing ever starts.++You can override the choice:++```bash title="Force a backend"+sudo beacon endpoint install --system --service systemd+sudo beacon endpoint install --system --service none+```++| Value | Behavior |+|---|---|+| `auto` (default) | systemd when it is PID 1, otherwise supervised |+| `systemd` | Require systemd; fail rather than fall back |+| `none` | A supervised background collector, tracked by a pidfile |++Use `--service systemd` in automation where a silent fallback would be worse than a failure. Use+`--service none` in a container or on a distribution without systemd.++## User-mode install++If you do not want a system service — a shared host where you are not root, or a machine where you+only want your own sessions captured — install in user mode:++```bash title="User-mode install"+beacon endpoint install+```++This writes everything under `~/.beacon/endpoint` and registers a `systemctl --user` unit. One+caveat has no macOS equivalent and is worth stating plainly: **a `--user` unit stops when you log+out**, unless linger is enabled for your account. Beacon enables it during install when it can, and+`beacon endpoint doctor` reports it when it could not:++```bash title="Keep a user-mode collector running after logout"+sudo loginctl enable-linger $USER+```++Without linger, a user-mode collector works while you are logged in and silently stops collecting+after you log out.++## Without systemd++The supervised backend covers hosts with no init system to talk to — containers, minimal images,+distributions using OpenRC or SysV:++```bash title="Supervised collector"+beacon endpoint install --service none+```++The collector runs as a background process tracked by a pidfile. It collects normally, but nothing+restarts it if it exits and nothing starts it at boot. `beacon endpoint status` states this rather+than reporting the same health as a managed service, so you are never misled about what you have.++For CI, prefer `beacon ci exec`, which wraps a single command in an ephemeral collector and needs no+service at all.++## Updates++Upgrade the package the way you installed it, or let Beacon do it:++```bash title="Update in place"+sudo beacon endpoint update --check+sudo beacon endpoint update --apply+```++`--apply` downloads the release package for your platform, verifies its SHA-256, installs it with+`dpkg` or `rpm`, restarts the collector, and rolls back if the new version fails its health check.+Verification is checksum-over-HTTPS from GitHub Releases — the same trust root you used to download+the package in the first place. macOS additionally verifies Apple notarization; Linux has no+OS-level equivalent, and `beacon endpoint update` reports which verification it performed rather+than implying both.++Upgrading the package keeps your configuration and your collected log.++## Uninstall++```bash title="Remove, keeping config and logs"+sudo apt remove beacon # or: sudo dnf remove beacon+```++Removal stops and deletes the service and takes the binaries away, but leaves+`/etc/beacon/endpoint` and `/var/log/beacon-agent` alone — collected telemetry is not something a+package removal should destroy. To remove those too:++```bash title="Remove everything"+sudo apt purge beacon+```++On RPM systems, or to remove a non-package install, use Beacon directly:++```bash title="Full uninstall"+sudo beacon endpoint uninstall --system+```++`--keep-logs` and `--keep-config` are available if you want to keep either.++## Related++<Columns cols={2}>+ <Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">+ Inspect collector health, runtime log state, harnesses, and diagnostics.+ </Card>+ <Card title="Endpoint paths and ports" icon="folder-tree" href="/cli/endpoint-paths">+ Where Beacon writes config, logs, and service definitions on each platform.+ </Card>+ <Card title="Endpoint install" icon="download" href="/cli/endpoint-install">+ All install flags, harness selection, and hook installation.+ </Card>+ <Card title="Endpoint doctor" icon="stethoscope" href="/cli/endpoint-doctor">+ Diagnose and repair an existing install.+ </Card>+</Columns>diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex 21cb0bed..7090fb52 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -7,16 +7,32 @@ description: "Review Beacon user-mode and system-mode paths, ports, and hook locBeacon manages different paths depending on whether you install in user mode or system mode. The active runtime log stays at `runtime.jsonl` and rotates at 10 MiB, retaining five numbered local archives by default.-| 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` |-| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` |-| Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` |-| Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` |-| OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` |-| OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` |+| Item | User mode | System mode (macOS) | System mode (Linux) |+|------|-----------|---------------------|---------------------|+| Config | `~/.beacon/endpoint/config.json` | `/Library/Application Support/Beacon/Endpoint/config.json` | `/etc/beacon/endpoint/config.json` |+| Base directory | `~/.beacon/endpoint` | `/Library/Application Support/Beacon/Endpoint` | `/etc/beacon/endpoint` |+| Runtime log | `~/.beacon/endpoint/logs/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` |+| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` |+| Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` | `/etc/beacon/endpoint/rules` |+| Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` | `/etc/beacon/endpoint/otelcol.yaml` |+| OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` |+| OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |++## Service Definitions++The collector runs under whichever service manager the host provides. Beacon picks it by looking at+what is actually running as PID 1, not at which tools are installed, so a container with+`systemctl` on `PATH` but no systemd still gets the supervised fallback.++| Platform | Service manager | System mode | User mode |+|---|---|---|---|+| macOS | launchd | `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` | `~/Library/LaunchAgents/com.beacon.endpoint.collector.plist` |+| Linux | systemd | `/etc/systemd/system/beacon-collector.service` | `~/.config/systemd/user/beacon-collector.service` |+| Containers, no init | supervised | `/etc/beacon/endpoint/collector.pid` | `~/.beacon/endpoint/collector.pid` |++A supervised collector is a plain background process tracked by a pidfile. It works, but nothing+restarts it if it exits or when the machine reboots — `beacon endpoint status` says so explicitly+rather than reporting the same health as a real service.Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, and OpenCode hooks install an embedded `beacon-hooks` adapter under the Beacon endpoint base directory.diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex c9c3df8b..c77cc8a2 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -26,7 +26,7 @@ During repair, Beacon removes the existing managed service before reinstalling i| `--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 |+| `--no-start` | Write files without starting the collector service || `--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 high-volume Codex OTLP spans for troubleshooting. By default, Beacon records Codex semantic logs and suppresses raw Codex spans || `--splunk-hec-endpoint <url>` | Splunk HEC endpoint URL |diff --git a/docs/cli/endpoint-status.mdx b/docs/cli/endpoint-status.mdxindex d21808a4..19202b08 100644--- a/docs/cli/endpoint-status.mdx+++ b/docs/cli/endpoint-status.mdx@@ -5,7 +5,9 @@ description: "Inspect local Beacon endpoint health, diagnostics, and runtime log## Command Overview-`beacon endpoint status` reports the current local endpoint configuration, collector status, launchd service state, discovered harnesses, diagnostics, destination status, and the last observed Beacon event.+`beacon endpoint status` reports the current local endpoint configuration, collector status, service state, discovered harnesses, diagnostics, destination status, and the last observed Beacon event.++The service state names the backend it found: `launchd` on macOS, `systemd` on Linux, or `supervised` where there is no init system to register with. A supervised collector is reported as such rather than as a healthy service, because nothing restarts it.```bash title="Command syntax"beacon endpoint status@@ -54,7 +56,7 @@ Status includes:- Config path and runtime log path- Runtime-log source warnings if a system collector may be writing OTLP events to a different log- Collector health and configured OTLP ports-- launchd service status+- Service status, and which service manager it came from- Discovered agent harnesses, including Beacon-managed or customer-managed telemetry state for Gemini CLI, VS Code Copilot, GitHub Copilot CLI, and Factory Droid when present- Endpoint diagnostics- Destination configuration in JSON output, including Splunk HEC or Falcon LogScale HEC endpoint, index, source, and sourcetype when configureddiff --git a/docs/deployment/open-source.mdx b/docs/deployment/open-source.mdxindex d13c9977..13ddaa52 100644--- a/docs/deployment/open-source.mdx+++ b/docs/deployment/open-source.mdx@@ -45,7 +45,7 @@ beacon endpoint install --harness claude,codex,gemini```<Note>- Production endpoint install is currently supported on macOS. The default mode uses per-user paths; use `--system` as root for package or MDM deployments.+ System-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. The default mode uses per-user paths; use `--system` as root for package or MDM deployments. On Linux, installing the `.deb` or `.rpm` does the system install for you — see [Linux install](/cli/endpoint-linux).</Note>Beacon records supported prompt, tool, command, file, approval, policy, and runtime context when the source runtime emits it. Before events are written to `runtime.jsonl` or sent through configured destinations, Beacon applies redaction, sanitization, truncation, and event-size limits.diff --git a/docs/docs.json b/docs/docs.jsonindex d8d7a9e9..5f46ebea 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -329,6 +329,7 @@"root": "cli/endpoint","pages": ["cli/endpoint-install",+ "cli/endpoint-linux","cli/endpoint-status","cli/endpoint-doctor","cli/endpoint-inventory",