Linux Install

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

Debian, Ubuntu, Fedora, RHEL, Rocky, Alma

curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash

The installer downloads the latest .deb or .rpm for your architecture into a temporary directory, checks it against the release checksums, installs it with apt-get or dnf, and cleans up. Set BEACON_VERSION=<version> to install a specific release. To run the same steps yourself, use the block for your distribution:

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
PKG="beacon_${VERSION}_linux_$(dpkg --print-architecture).deb"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
DIR="$(mktemp -d /tmp/beacon-install.XXXXXXXX)" && chmod 0711 "$DIR" && cd "$DIR"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt" && chmod 0644 "${PKG}"
grep "  ${PKG}$" checksums.txt | sha256sum --check - && sudo apt install "./${PKG}"

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
case "$(uname -m)" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
PKG="beacon_${VERSION}_linux_${ARCH}.rpm"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt"
grep "  ${PKG}$" checksums.txt | sha256sum --check - && sudo dnf install "./${PKG}"

amd64 and arm64 packages are published for both formats. The package puts beacon on your PATH, so every command below works by name.

APT reads a local package as its unprivileged _apt user. If the .deb sits somewhere _apt cannot read, such as your home directory, the install still succeeds, but APT ends with Download is performed unsandboxed as root and pkgAcquire::Run (13: Permission denied). That is a warning, not a failure, and there is nothing to repair; beacon version confirms the install. The installer and the Debian block above download into a readable directory under /tmp so the warning does not appear.

Without root, or without a package manager

If you are not an administrator on the machine, or you would rather not touch system paths, use the tarball and install in user mode:

Tarball install, no root required

LATEST_URL="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"
VERSION="${LATEST_URL##*/v}"

case "$(uname -m)" in
  x86_64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
  *) echo "Beacon publishes Linux archives for amd64 and arm64, not $(uname -m)" >&2; exit 1 ;;
esac

ARCHIVE="beacon_${VERSION}_linux_${ARCH}.tar.gz"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${ARCHIVE}"
curl -fsSLO "${BASE}/checksums.txt"

# Verify this exact archive before extracting it, by the name about to be extracted.
grep "  ${ARCHIVE}$" checksums.txt | sha256sum --check -

tar -xzf "${ARCHIVE}"
mkdir -p ~/.local/bin && mv beacon beacon-hooks beacon-otelcol beacon-vector ~/.local/bin/

# ~/.local/bin is already on PATH on most distributions; if `beacon version` fails, add it:
#   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && exec $SHELL
beacon version
beacon endpoint install

The version comes from the current release rather than a number you have to keep up to date, and the architecture comes from uname -m: x86_64 maps to the published amd64 archive and aarch64 to arm64. An architecture Beacon does not publish stops the run before anything is downloaded. The archive contains four binaries: the beacon CLI, the beacon-hooks adapter that captures tool activity, the beacon-otelcol collector, and beacon-vector, which is Vector for forwarding (see Forwarding). The first three are needed. beacon-vector only runs if you set up a destination that uses it, and it is named that so it cannot shadow a vector you already have on PATH. All four are statically linked with no shared-library dependencies. See User-mode install for what this sets up and its one caveat.

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.

Confirm it worked

Check the endpoint

beacon endpoint status --system

Beacon Endpoint Agent <version>
Config: /etc/beacon/endpoint/config.json
Runtime log: /var/log/beacon-agent/runtime.jsonl
Collector: grpc=true http=true
Service: loaded=true running=true
Harness: Claude Code  telemetry=enabled
Last event: present
Inventory heartbeat: scheduled every 6h0m0s; job loaded=true running=true; last emitted never

running=true and telemetry=enabled are the lines that matter. Then run your agent as usual (see Using it) and its events land in the runtime log.

If something looks wrong

beacon endpoint doctor --system checks the whole chain (unit, collector, config, log permissions, and each harness’s settings) and prints the command that fixes anything it finds. What matters is 0 failure(s). Before you have run an agent it warns harness_observed, which clears the first time you do.

One failure is worth knowing by name, because a system endpoint can be perfectly healthy and still be capturing nobody:

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"

A system-mode endpoint runs as root, so it has to work out whose agent settings to configure. If it could not identify you at install time, the collector still starts and reports healthy, but nothing is sending to it. Run the action above as the user whose sessions should be captured and it clears.

To test the pipeline without running an agent, write a synthetic event with sudo beacon endpoint test-event --system. Keep the --system: without it the command writes to the user-mode log under ~/.beacon and reports success against the wrong file.

Using it

Nothing to remember. Run your agent the way you normally do:

claude

Prompts, the commands the agent runs, files it reads and writes, token counts and cost, and approvals and denials all land in /var/log/beacon-agent/runtime.jsonl, one JSON object per line. Two independent paths feed it, so a gap in one still leaves you with data:

Path	Carries
OpenTelemetry	Prompts, tool calls, token usage, and cost, through `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings
Hooks	Session start and end, tool use, permission requests, subagent activity, and reasoning

Both are loopback-only. Nothing leaves the machine. From there:

Look at what was captured

beacon endpoint dashboard    # local web view of sessions, timelines, and event detail
beacon scan                  # run threat detection rules over the log
beacon token-usage           # token and cost rollups

See the event schema for the full field reference.

Forwarding

A new install is local-only. Nothing leaves the machine until you set up a destination, and each one reads the same local log.

Destination	What ships the events
Splunk	The collector, over HEC
Elastic, Datadog, Wazuh	That product’s own agent, tailing the log
Microsoft Sentinel	Vector, through the Logs Ingestion API. Or Azure Monitor Agent, which outside Azure needs Azure Arc first
S3, GCS, CloudWatch, Sumo Logic, Rapid7, CrowdStrike Falcon	Vector
Asymptote Managed	Vector, set up by `beacon endpoint connect`

Vector comes with Beacon. The .deb and .rpm install it at /opt/beacon/bin/vector, and the tarball carries it as beacon-vector. Neither is on PATH by default, and neither runs until a destination needs it. beacon endpoint connect finds it on its own. For the other Vector destinations, run the generated vector.toml with /opt/beacon/bin/vector, or with your own Vector 0.50 or newer.

What the install does

Step	Result
Unpack	`beacon`, `beacon-hooks`, `beacon-otelcol` and `vector` 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, and the collector is useless if nothing exports 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:

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. That 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. To stop other accounts from modifying or reading it, install with --log-access restricted: the collector becomes the only writer and hooks send their events to it over a local socket.

Managing the service

The unit is an ordinary systemd service, so the usual commands work:

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:

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:

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

Install in user mode if you do not want a system service, either because you are not root on a shared host or because you only want your own sessions captured:

User-mode install

beacon endpoint install

On an interactive terminal this opens the setup wizard, which asks you to sign in. Sign-in finishes in a browser on this machine, so over SSH or with no display the wizard says so straight away and offers to finish without an account, or to show the sign-in URL with the ssh -L command for opening it on your own computer. See Onboarding. BEACON_ONBOARDING=0 skips the wizard, and package installs never show it. 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:

Keep a user-mode collector running after logout

sudo loginctl enable-linger $USER

When it could not, beacon endpoint install and beacon endpoint repair say so at the end of the run and print that exact command, and beacon endpoint doctor keeps reporting it until it is fixed. Beacon checks the resulting linger state rather than the exit status of its own attempt, so this reflects whether the collector really will survive logout. Without linger, a user-mode collector works while you are logged in and stops collecting after you log out.

Without systemd

The supervised backend covers hosts with no init system to talk to, such as containers, minimal images, and distributions using OpenRC or SysV:

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:

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

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:

Remove everything (Debian, Ubuntu)

sudo apt purge beacon

RPM has no purge. Run Beacon’s own uninstall first, while the binary is still there, then remove the package:

Remove everything (RHEL, Rocky, Fedora)

sudo beacon endpoint uninstall --system
sudo dnf remove beacon

beacon endpoint uninstall --system on its own also removes a non-package install. --keep-logs and --keep-config are available if you want to keep either.

Deployment profile

What it depends on, what it costs to run, and how to verify both, for a security review.

Endpoint status

Inspect collector health, runtime log state, harnesses, and diagnostics.

Endpoint paths and ports

Where Beacon writes config, logs, and service definitions on each platform.

Endpoint install

All install flags, harness selection, and hook installation.

Endpoint doctor

Diagnose and repair an existing install.

Local dashboard

Browse captured sessions, timelines, and event detail locally.

Threat detection

Run the open threat rules over your runtime log, offline.

Install and Upgrade

CLI Resources

Command Manual

Install

Without root, or without a package manager

Confirm it worked

If something looks wrong

Using it

Forwarding

What the install does

Managing the service

Choosing a service backend

User-mode install

Without systemd

Updates

Uninstall

Deployment profile

Endpoint status

Endpoint paths and ports

Endpoint install

Endpoint doctor

Local dashboard

Threat detection

​Install

​Without root, or without a package manager

​Confirm it worked

​If something looks wrong

​Using it

​Forwarding

​What the install does

​Managing the service

​Choosing a service backend

​User-mode install

​Without systemd

​Updates

​Uninstall

​Related

Deployment profile

Endpoint status

Endpoint paths and ports

Endpoint install

Endpoint doctor

Local dashboard

Threat detection

Install

Without root, or without a package manager

Confirm it worked

If something looks wrong

Using it

Forwarding

What the install does

Managing the service

Choosing a service backend

User-mode install

Without systemd

Updates

Uninstall

Related