> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux Install

> 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" theme={null}
  sudo apt install ./beacon_<version>_linux_amd64.deb
  ```

  ```bash title="Fedora, RHEL, Rocky, Alma" theme={null}
  sudo dnf install ./beacon-<version>-linux-amd64.rpm
  ```
</CodeGroup>

`amd64` and `arm64` packages are published for both formats.

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

## Confirm it worked

```bash title="Verify the install" theme={null}
beacon endpoint status --system
```

```
Beacon Endpoint Agent 1.0.6
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
```

`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:

```
Beacon endpoint doctor: warn
harness_observed: warn target=claude_code (telemetry is configured but no matching event has
  been observed yet) action="run Claude Code or beacon endpoint test-event"
Summary: 0 failure(s), 1 warning(s)
```

That says "configured correctly, but you have not used it yet." It clears the first time you run
your agent. What matters is `0 failure(s)`.

If you would rather confirm the pipeline before running a real session, write a synthetic event:

```bash title="Prove the collector is receiving and writing events" theme={null}
sudo beacon endpoint test-event --system
```

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

## Using it

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

```bash theme={null}
claude
```

Prompts, the commands the agent runs, files it reads and writes, token counts and cost, approvals
and denials all land in `/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:

| Path          | Carries                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| OpenTelemetry | Prompts, tool calls, token usage, cost — via `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, reasoning                                      |

Both are loopback-only. Nothing leaves the machine.

From there:

```bash title="Look at what was captured" theme={null}
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](/telemetry-schema/event-schema) for the full field reference.

## 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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
sudo apt purge beacon
```

On RPM systems, or to remove a non-package install, use Beacon directly:

```bash title="Full uninstall" theme={null}
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>

  <Card title="Local dashboard" icon="chart-line" href="/cli/dashboard">
    Browse captured sessions, timelines, and event detail locally.
  </Card>

  <Card title="Threat detection" icon="shield-halved" href="/cli/scan">
    Run the open threat rules over your runtime log, offline.
  </Card>
</Columns>