Install
Download the package for your architecture from the latest release and install it:amd64 and arm64 packages are published for both formats.
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
Verify the install
beacon endpoint doctor --system goes further, checking the whole chain — unit, collector, config,
log permissions, and each harness’s settings — and printing the command to fix anything it finds.
On a fresh install it reports one warning, and it is not a problem:
0 failure(s).
If you would rather confirm the pipeline before running a real session, write a synthetic event:
Prove the collector is receiving and writing events
Pass
--system here. Without it the command targets the user-mode log under ~/.beacon, which
is not the log a system install writes to — so it would report success against the wrong file.Using it
Nothing to remember. Run your agent the way you normally do:/var/log/beacon-agent/runtime.jsonl — one JSON object per line. Two
independent paths feed it, which is why a gap in one still leaves you with data:
Both are loopback-only. Nothing leaves the machine.
From there:
Look at what was captured
What the install does
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:
Configure your own agent runtime against an already-installed endpoint
/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:Service management
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
Choosing a service backend
Beacon decides which service manager to use by reading what is actually running as PID 1. It does not check whethersystemctl 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
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:User-mode install
~/.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:
Keep a user-mode collector running after logout
Without systemd
The supervised backend covers hosts with no init system to talk to — containers, minimal images, distributions using OpenRC or SysV:Supervised collector
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
--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
/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
Full uninstall
--keep-logs and --keep-config are available if you want to keep either.
Related
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.