Skip to content

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

7.8 KB
Raw Blame
---
title: "Linux Deployment Profile"
description: "What the Beacon endpoint agent depends on, what it costs to run, and how to verify both yourself"
---

A reference for reviewing Beacon before deploying it. Each claim comes with the command that checks it, so you can confirm any of this yourself.

## Kernel surface

Beacon loads nothing into the kernel and needs nothing beyond a standard POSIX system.

| | |
|---|---|
| Kernel modules | None loaded, none required |
| eBPF / audit subsystem | Not used |
| netlink | `NETLINK_SOCK_DIAG` per OpenTelemetry export, to look up which account owns the sending loopback connection: one exact query, or two for an IPv4 connection (as IPv4, then as an IPv4-mapped IPv6 address) |
| ptrace, process injection | Not used |
| cgroups, `/sys`, udev | Not read |
| Capabilities, setuid, setcap | None |
| `/proc` | `/proc/1/comm`, to detect whether systemd is PID 1; `/proc/net/tcp` and `/proc/net/tcp6` for the same connection lookup when the `NETLINK_SOCK_DIAG` query fails, and when it finds nothing before it has once found a socket (the kernel answers the same way when the `tcp_diag` module is missing) |

Everything it uses from the kernel:

| Facility | Used for | If unavailable |
|---|---|---|
| TCP loopback | Three listeners on `127.0.0.1` | Collector cannot start |
| `flock(2)` | Serializing writes to the runtime log | Degrades on some network filesystems; fine on local disk |
| `fork`/`exec` | One short-lived hook process per agent event. The collector also runs `/usr/bin/id -nu <uid>` (500 ms limit) to name a sender whose account is not in `/etc/passwd`, such as an LDAP, SSSD or AD account, at most once per account every 10 minutes | Hook capture stops; OpenTelemetry capture continues. Without `id`, a directory account's events carry its uid without a name |
| Ordinary file I/O | Config and log | None |
| `/proc/1/comm` | systemd detection | Falls back to a supervised collector, which does not restart on exit or start at boot |
| `NETLINK_SOCK_DIAG`, `/proc/net/tcp{,6}` | Recording each OpenTelemetry export under the account that sent it | The export is recorded with no account, never as root or anyone else |

To see the syscalls for yourself:

```bash
sudo strace -f -c -p "$(pgrep -n beacon-otelcol)"   # collector, steady state
sudo strace -f -c -o /tmp/install.trace beacon endpoint install --system --dry-run
```

## Binaries

Four static executables, no shared libraries, no minimum glibc version. They run the same on a minimal or older userland as on a full one.

| Binary | Role | Resident? |
|---|---|---|
| `beacon-otelcol` | Collector | Yes, the only long-running process |
| `beacon-hooks` | Records one agent event | No, it forks and exits |
| `beacon` | CLI | No |
| `vector` | Forwarder ([Vector](https://vector.dev) 0.56) | Only if you set up a destination that uses it |

```bash
file /opt/beacon/bin/beacon-otelcol     # ... statically linked
ldd  /opt/beacon/bin/beacon-otelcol     # not a dynamic executable
readelf -l /opt/beacon/bin/beacon-otelcol | grep INTERP   # no output = static
```

CI fails the build if a Linux binary is ever dynamically linked.

## Footprint

Measured on Ubuntu 24.04 / amd64 after a live Claude Code session.

| | Measured | Notes |
|---|---|---|
| Resident memory | 28-58 MiB | Hard ceiling 128 MiB (`memory_limiter`) |
| CPU, idle | 0.03-0.3% of one core | Two timers: 1s memory check, 5s batch flush |
| Threads | 15 | Go runtime, scales with available cores |
| Disk, log | ≤60 MB | 10 MiB × 5 rotations, oldest discarded |
| Disk, package | ~220 MB installed, ~86 MB download (amd64) | About 150 MB of it is Vector |
| Per agent event | one `fork`/`exec`, one `flock`, one append | Process exits immediately |

### Caveats

- Both figures are ranges, not averages. They come from a supervised collector and a systemd-managed one, which accounts for most of the spread. Memory in particular depends on how much the Go runtime has been asked to do before it settles.
- These numbers come from a virtualized sandbox, where syscalls are slower than on bare metal.
  Expect equal or better on your own hardware.

### Measuring it yourself

```bash
pid=$(pgrep -n beacon-otelcol)
grep -E 'VmRSS|Threads' /proc/$pid/status
awk '{print $14+$15}' /proc/$pid/stat    # sample twice, 30s apart; (delta/100)/30 = fraction of a core
```

## Network

Beacon listens on loopback only, and collection never sends anything off the machine.

| Listener | Port | Bind |
|---|---|---|
| OTLP gRPC | 4317 | `127.0.0.1` |
| OTLP HTTP | 4318 | `127.0.0.1` |
| Health check | 13133 | `127.0.0.1` |

The only outbound connections Beacon ever makes, for an egress allowlist:

| Host | When | Suppress with |
|---|---|---|
| `auth.asymptotelabs.ai` | Once per machine, interactive install only | `BEACON_ONBOARDING=0` (already skipped for `--system` and package installs) |
| `beacon.sh` | Interactive install only: browser sign-in, and the device enrollment that follows when Beacon Cloud is confirmed | `BEACON_MANAGED_INGEST=0` hides the managed answer; `BEACON_ONBOARDING=0` skips the wizard entirely |
| Your ingest host | Continuously, only on an endpoint connected to Beacon Cloud | `beacon endpoint disconnect`, or never connecting |
| `api.github.com`, `github.com` | Version check and self-update | Off by default; leave it off and deploy through your config management |

A forwarding destination you set up yourself, such as Splunk HEC, or Microsoft Sentinel through Vector, connects to that destination's hosts. Nothing does until you configure one.

```bash
ss -ltnp | grep beacon-otelcol
```

## Privileges and data

- In system mode the collector runs as root. Hooks run as the logged-in user and append to the same
  log, which is why `/var/log/beacon-agent/runtime.jsonl` is mode `0666`. With
  [`--log-access restricted`](/cli/endpoint-install#restricted-log-access) the collector is the only
  writer instead: hooks send events to it over `/var/run/beacon-agent/ingest.sock`, the log is
  `0640 root:beacon-log`, and log shippers that do not run as root join the `beacon-log` group.
- In user mode everything runs as you under `~/.beacon`, with no privileges required.
- The log contains prompt text, command lines, file paths, and tool inputs, after redaction and a
  64 KiB per-event limit. Treat it as sensitive data.
- The CLI looks accounts up through `getent`, and the collector names a sender from `/etc/passwd` and then `id -nu`, so accounts from OpenLDAP, SSSD, or AD resolve normally.

## Pinning it to housekeeping cores

If you isolate cores for latency-sensitive work, keep Beacon off them. It only has two slow timers, but a timer firing on an `isolcpus` or `nohz_full` core is exactly what isolating that core was meant to prevent.

```ini
# /etc/systemd/system/beacon-collector.service.d/10-resources.conf
[Service]
CPUAffinity=0-3          # your housekeeping cores, NOT the isolated set
CPUQuota=5%
MemoryMax=192M
Nice=19
IOSchedulingClass=idle
```

```bash
sudo systemctl daemon-reload && sudo systemctl restart beacon-collector
systemctl show beacon-collector -p CPUAffinity -p CPUQuota -p MemoryMax
```

Put this in a drop-in rather than editing the unit file directly. `beacon endpoint doctor --fix` rewrites the unit, which would wipe out your changes; drop-ins are left alone.

## Uninstall

```bash
sudo apt remove beacon     # keeps config and collected logs
sudo apt purge beacon      # removes them
```

On RPM systems, `dnf remove` keeps `/etc/beacon/endpoint` and `/var/log/beacon-agent`, and there is no purge. To remove the data too, run `sudo beacon endpoint uninstall --system` before `sudo dnf remove beacon`; afterwards the `beacon` binary is gone.

## Related

<Columns cols={2}>
  <Card title="Linux install" icon="download" href="/platforms/linux">
    Packages, user-mode installs, and service management.
  </Card>
  <Card title="Data inventory" icon="database" href="/security/data-inventory">
    Exactly which fields are recorded and retained.
  </Card>
</Columns>