The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
docs(linux): add a deployment profile, and make its central claim enforceable
shukieshaha3daaf39e3dd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 7983a4eb..d1bbbdc8 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -147,6 +147,28 @@ jobs:working-directory: cli/beaconrun: 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-lateststeps:diff --git a/beacon-sandbox/runner/runner.go b/beacon-sandbox/runner/runner.goindex 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 Optart.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/Makefileindex 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 variablesBINARY := beacon-hooksLDFLAGS := -s -wdiff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yamlindex 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-hooksdir: ../beacon-hooksdiff --git a/cli/beacon/Makefile b/cli/beacon/Makefileindex 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 variablesVERSION ?= $(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.jsonindex 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.mdxnew file mode 100644index 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.mdxindex 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>