Skip to content

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

docs(linux): add a deployment profile, and make its central claim enforceable

shukieshaha3daaf39e3dd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7983a4eb..d1bbbdc8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -147,6 +147,28 @@ jobs:
working-directory: cli/beacon
run: make ${{ matrix.make_target }}
+ # Linux binaries must be statically linked, and this runner is where that can regress: a
+ # linux target here is a native build with a C toolchain present, so cgo defaults on and the
+ # net package selects the libc resolver. The result carries a glibc version floor that works
+ # on this runner and fails on an older or stripped host -- exactly the customers who cannot
+ # easily diagnose it. Checked on the ELF header rather than by running ldd, which reports
+ # "not a dynamic executable" to stdout or stderr depending on version.
+ - name: Linux binaries must be statically linked
+ if: matrix.goos == 'linux'
+ working-directory: cli/beacon
+ run: |
+ set -eu
+ for bin in "beacon-linux-${{ matrix.goarch }}" \
+ "../beacon-hooks/beacon-hooks-linux-${{ matrix.goarch }}"; do
+ if readelf -l "$bin" | grep -q INTERP; then
+ echo "$bin is dynamically linked: it has a PT_INTERP segment naming a dynamic loader." >&2
+ echo "A release built this way fails on hosts whose glibc predates the build host's." >&2
+ readelf -l "$bin" | grep -A1 INTERP >&2
+ exit 1
+ fi
+ echo "ok: $bin is statically linked"
+ done
+
linux-test:
runs-on: ubuntu-latest
steps:
diff --git a/beacon-sandbox/runner/runner.go b/beacon-sandbox/runner/runner.go
index 0bb99e4f..63ed5f3f 100644
--- a/beacon-sandbox/runner/runner.go
+++ b/beacon-sandbox/runner/runner.go
@@ -449,6 +449,18 @@ func Run(ctx context.Context, p sandbox.Provider, sc scenario.Scenario, opts Opt
art.Meta["quiescence_seconds"] = fmt.Sprintf("%.0f", waited.Seconds())
art.Meta["quiescent"] = fmt.Sprintf("%v", stable)
+ // Measured after quiescence, so the collector is resident and idle rather than mid-batch.
+ // Only for install scenarios: a `ci exec` collector is torn down with the command and has no
+ // steady state to describe. Recorded rather than asserted -- these are the numbers a customer
+ // evaluating footprint asks for, and publishing an estimate instead of a measurement is how a
+ // resource claim quietly stops being true.
+ if sc.Install != nil {
+ if snap := collectorFootprint(ctx, g, agent); snap != "" {
+ art.Meta["collector_footprint"] = snap
+ logf("collector footprint: %s", snap)
+ }
+ }
+
localLog := filepath.Join(runDir, "runtime.jsonl")
if err := g.Get(ctx, logPath, localLog); err != nil {
return art, fmt.Errorf("collect runtime log: %w", err)
@@ -588,6 +600,45 @@ func imageSpecFor(p sandbox.Platform, sc scenario.Scenario, opts Options,
}, logf)
}
+// collectorFootprint measures the resident collector: memory, threads, descriptors, and the CPU it
+// consumes while idle.
+//
+// Read from /proc rather than from ps output formats that differ between distributions, and
+// sampled over a fixed interval because idle CPU is a rate, not a value -- the total ticks a
+// process has ever used says nothing about what it costs to leave running.
+//
+// Best-effort by design: this describes a run, it does not gate one. A shell that cannot produce
+// the numbers returns an empty string and the scenario proceeds, because a footprint measurement
+// failing is not a reason to fail a capture test.
+func collectorFootprint(ctx context.Context, g guest, opts sandbox.ExecOpts) string {
+ // Sampled over 30s rather than 10s: at 100 ticks/second an idle collector accumulates about
+ // one tick per 10s, so a 10s window reports 0 or 1 and cannot distinguish "almost nothing"
+ // from "nothing". 30s buys a figure with more than one significant digit.
+ //
+ // The descriptor count needs sudo. In system mode the collector runs as root while this shell
+ // runs as the agent user, so /proc/<pid>/fd is not readable and a plain `ls` yields zero --
+ // a number that is not merely imprecise but impossible, since every process holds at least
+ // stdin, stdout, and stderr. "unreadable" is reported instead, because publishing a resource
+ // figure that is obviously false costs more credibility than omitting one.
+ const script = `
+pid=$(pgrep -n beacon-otelcol 2>/dev/null) || exit 0
+[ -n "$pid" ] || exit 0
+read_ticks() { awk '{print $14+$15}' /proc/$1/stat 2>/dev/null; }
+t0=$(read_ticks "$pid"); sleep 30; t1=$(read_ticks "$pid")
+hz=$(getconf CLK_TCK 2>/dev/null || echo 100)
+rss=$(awk '/^VmRSS:/{print $2}' /proc/$pid/status 2>/dev/null)
+thr=$(awk '/^Threads:/{print $2}' /proc/$pid/status 2>/dev/null)
+fds=$(sudo ls /proc/$pid/fd 2>/dev/null | wc -l | tr -d ' ')
+[ "${fds:-0}" -gt 0 ] 2>/dev/null || fds=unreadable
+echo "rss_kb=${rss:-?} threads=${thr:-?} fds=${fds} cpu_ticks_per_30s=$((t1-t0)) clk_tck=$hz"
+`
+ res, err := g.Exec(ctx, script, opts)
+ if err != nil || res.ExitCode != 0 {
+ return ""
+ }
+ return oneLine(res.Stdout)
+}
+
func randomToken() string {
b := make([]byte, 6)
if _, err := rand.Read(b); err != nil {
diff --git a/cli/beacon-hooks/Makefile b/cli/beacon-hooks/Makefile
index 86c75c3c..9baae9e0 100644
--- a/cli/beacon-hooks/Makefile
+++ b/cli/beacon-hooks/Makefile
@@ -1,5 +1,10 @@
# Beacon Hooks Makefile
+# Static binaries, always. See cli/beacon/Makefile for why; this binary is the one that matters
+# most, because it is embedded in the CLI and extracted at install time, so a dynamic build here
+# fails on the target host rather than on the build host.
+export CGO_ENABLED = 0
+
# Build variables
BINARY := beacon-hooks
LDFLAGS := -s -w
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index feba7647..ff354221 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -54,7 +54,12 @@ builds:
# --parallelism 1 so target builds cannot race here. The -a flag above
# forces a full rebuild for each target so Go re-reads the freshly-built
# hooks.bin instead of serving a stale copy from cache.
- - cmd: bash -c 'cd ../beacon-hooks && GOOS={{ .Os }} GOARCH={{ .Arch }} go build -ldflags "-s -w -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{ .Version }}" -o ../beacon/internal/embedded/hooks.bin .'
+ # CGO_ENABLED=0 matters here as much as it does in the builds above. Releases are built on
+ # Linux, so a linux/amd64 target is a native build with a C toolchain present, and cgo
+ # would default on. beacon-hooks pulls in net, which selects the cgo resolver and links
+ # libc -- producing a dynamically linked hooks binary embedded inside a statically linked
+ # CLI, with a glibc version floor that only shows up on an older or stripped host.
+ - cmd: bash -c 'cd ../beacon-hooks && CGO_ENABLED=0 GOOS={{ .Os }} GOARCH={{ .Arch }} go build -ldflags "-s -w -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{ .Version }}" -o ../beacon/internal/embedded/hooks.bin .'
output: true
- id: beacon-hooks
dir: ../beacon-hooks
diff --git a/cli/beacon/Makefile b/cli/beacon/Makefile
index e630eb4f..4b473e22 100644
--- a/cli/beacon/Makefile
+++ b/cli/beacon/Makefile
@@ -1,5 +1,13 @@
# Beacon CLI Makefile
+# Static binaries, always, matching what the release builds.
+#
+# Not cosmetic: cgo defaults on for a native build, so `make build-linux-amd64` produced a static
+# binary when cross-compiled from macOS and a dynamic one when run on Linux. The dynamic form
+# carries a glibc version floor that only fails on an older or stripped host -- the machines least
+# likely to be the one you tested on. Exported so every target gets it, including new ones.
+export CGO_ENABLED = 0
+
# Build variables
VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
GIT_COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
diff --git a/docs/docs.json b/docs/docs.json
index b01f0e1f..01d1265f 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -292,6 +292,7 @@
"pages": [
"platforms/macos",
"platforms/linux",
+ "platforms/linux-deployment-profile",
"platforms/windows"
]
},
diff --git a/docs/platforms/linux-deployment-profile.mdx b/docs/platforms/linux-deployment-profile.mdx
new file mode 100644
index 00000000..3e3eb155
--- /dev/null
+++ b/docs/platforms/linux-deployment-profile.mdx
@@ -0,0 +1,159 @@
+---
+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. Every claim names the command that checks it,
+so nothing here has to be taken on trust.
+
+## Kernel surface
+
+**Beacon loads nothing into the kernel and requires no kernel feature beyond a standard POSIX
+system.**
+
+| | |
+|---|---|
+| Kernel modules | None loaded, none required |
+| eBPF / netlink / audit subsystem | Not used |
+| ptrace, process injection | Not used |
+| cgroups, `/sys`, udev | Not read |
+| Capabilities, setuid, setcap | None |
+| `/proc` | One file: `/proc/1/comm`, to detect whether systemd is PID 1 |
+
+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 | Hook capture stops; OpenTelemetry capture continues |
+| Ordinary file I/O | Config and log | — |
+| `/proc/1/comm` | systemd detection | Falls back to a supervised collector, which does not restart on exit or start at boot |
+
+Verify the syscall surface on your own hardware rather than taking ours:
+
+```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
+
+Three static executables, no shared libraries, no glibc version floor. An older or stripped
+userland cannot produce a missing-library or wrong-symbol-version failure.
+
+| Binary | Role | Resident? |
+|---|---|---|
+| `beacon-otelcol` | Collector | Yes — the only long-running process |
+| `beacon-hooks` | Records one agent event | No — forks and exits |
+| `beacon` | CLI | No |
+
+```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 any Linux binary gains a dynamic loader, so this cannot regress quietly.
+
+## Footprint
+
+Measured on Ubuntu 24.04 / amd64 after a live Claude Code session, not estimated.
+
+| | Measured | Notes |
+|---|---|---|
+| Resident memory | ~57 MiB | Hard ceiling 128 MiB (`memory_limiter`) |
+| CPU, idle | 0.1–0.3% of one core | Two timers: 1s memory check, 5s batch flush |
+| Threads | 15 | Go runtime, scales with available cores |
+| Disk | ≤60 MB | 10 MiB × 5 rotations, oldest discarded |
+| Per agent event | one `fork`/`exec`, one `flock`, one append | Process exits immediately |
+
+Two caveats worth stating rather than hiding, since you will measure this yourself:
+
+- The CPU figure is a **range across runs**, not a single number. Repeated 30-second samples landed
+ between 0.1% and 0.3% of one core; publishing the midpoint would imply a precision the
+ measurement does not have.
+- It was measured inside a virtualized sandbox, where syscalls cost more than on bare metal. Treat
+ it as an **upper bound** for your hardware, not a prediction.
+
+Reproduce:
+
+```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
+
+Loopback only. Nothing is sent off the machine by normal collection.
+
+| Listener | Port | Bind |
+|---|---|---|
+| OTLP gRPC | 4317 | `127.0.0.1` |
+| OTLP HTTP | 4318 | `127.0.0.1` |
+| Health check | 13133 | `127.0.0.1` |
+
+Outbound, for an egress allowlist. None occurs during collection:
+
+| Host | When | Suppress with |
+|---|---|---|
+| `auth.asymptotelabs.ai` | Once per machine, interactive install only | `BEACON_ONBOARDING=0` (already skipped for `--system` and package installs) |
+| `api.github.com`, `github.com` | Version check and self-update | Off by default; leave it off and deploy through your config management |
+
+```bash
+ss -ltnp | grep beacon-otelcol
+```
+
+## Privileges and data
+
+- System mode runs the collector as **root**, because hooks running as the logged-in user append to
+ the same log. `/var/log/beacon-agent/runtime.jsonl` is mode `0666` for that reason.
+- User mode runs entirely as you, under `~/.beacon`, and needs no privileges.
+- The log holds **prompt text, command lines, file paths, and tool inputs**, subject to redaction and
+ a 64 KiB per-event cap. Treat it as sensitive.
+- Account lookup uses `getent`, so directory-backed accounts (OpenLDAP, SSSD, AD) resolve.
+
+## Confining it to housekeeping cores
+
+If you isolate cores for latency-sensitive work, pin Beacon away from them. Beacon's timers are few
+and slow, but a timer landing on an `isolcpus`/`nohz_full` core defeats the point of isolating it.
+
+```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
+```
+
+Use a drop-in, not an edit to the unit file: `beacon endpoint doctor --fix` rewrites the unit and
+would discard changes made there. Drop-ins survive.
+
+## 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`. Remove them
+with `sudo beacon endpoint uninstall --system` if you want the data 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>
diff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdx
index 84523f11..f2209220 100644
--- a/docs/platforms/linux.mdx
+++ b/docs/platforms/linux.mdx
@@ -294,6 +294,9 @@ sudo beacon endpoint uninstall --system
## Related
<Columns cols={2}>
+ <Card title="Deployment profile" icon="shield-check" href="/platforms/linux-deployment-profile">
+ What it depends on, what it costs to run, and how to verify both — for a security review.
+ </Card>
<Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
Inspect collector health, runtime log state, harnesses, and diagnostics.
</Card>