agentcap

AI coding agents run shell commands, open files, and make network calls on your machine, and most of it goes unseen. agentcap records that activity from the kernel with eBPF and exposes it as per-agent Prometheus metrics with a Grafana dashboard. It needs no SDK or changes to the agents, works on agents that are already running, and attributes child processes (a bash or curl a tool spawns) to the agent that launched them.

Per agent, it reports:

• tools run — each binary the agent exec'd
• domains queried and destination ports
• files opened, read vs. write
• CPU time, network bytes, file I/O, and process churn

That's enough to audit what an agent did, notice an unexpected domain or port, or track resource use over time. OpenClaw, Claude Code, Codex, Gemini, aider and others are recognized by default; add any process by name. Built on yeet and eBPF.

Quickstart

curl -fsSL https://yeet.cx | sh          # 1. install yeet (CLI + yeetd daemon)
yeet login                               # 2. authenticate this host
git clone https://github.com/yeet-src/agentcap && cd agentcap
make up                                  # 3. build + start the exporter on :9464
make wire                                # 4. print how to add it to your Grafana

make up runs the exporter (a Prometheus endpoint at 127.0.0.1:9464); make wire prints the scrape-config + dashboard-import steps for your Grafana. No Grafana handy? Run make demo for a throwaway Prometheus + Grafana in Docker at http://localhost:3000/d/agentcap/agent-activity. Full detail in Setup; make down stops everything.

Agents included

Tracked out of the box (edit src/agents.txt to change the list — one comm prefix per line):

Each name is a process-comm prefix; a match pulls in that process's whole tree, so the bash / node / curl an agent spawns is counted under it. Only agents actually running appear in the metrics — the list is the watch set, not a requirement that all be present.

How it watches agents

The BPF side (src/bpf/agentcap.bpf.c) is policy-free: the collector reads the prefix list from src/agents.txt and pushes it into a kernel LPM trie at startup, so matching is a single loop-free trie lookup with no per-agent cost. The word-boundary rule is encoded in the data — each prefix is inserted as name\0 / name- / name_ / name. — so "pi" catches pi, not pipewire. A task is tracked when its comm matches the trie or when a tracked task forks it — each tree keeps the identity of the prefix that rooted it, so a bash exec'd by openclaw is counted as agent="openclaw". Roots that predate the probe (a running gateway) are adopted on their first context switch, fork, or socket/file op.

Attach types: tracepoints, LSM hooks, and fexit trampolines — no kprobes. LSM (socket_connect, socket_sendmsg) carries exact before-the-fact semantics and is a stable security API; fexit supplies what LSM never sees: actual received bytes (sock_recvmsg) and actual file I/O (vfs_read/vfs_write). The LSM programs need a kernel with BPF-LSM available, which modern distros ship; if it isn't, the probe reports agentcap_probe_up 0 and the app stays up rather than crashing.

Egress is split by rate: rare lifecycle events (fork/exec/exit, with names) stream over a ring buffer; high-rate sums (CPU ns, socket and file bytes) live in a {agent, slot}-keyed hash the collector polls once a second.

Audit: domains and destination ports

For security review, the probe also streams, per agent, the destination port of every inet connect and the domain of every name lookup it can see. To keep the kernel side verifier-safe, the probe only filters and copies raw bytes; the collector parses them in JavaScript, where loops are free. Two lookup paths are covered:

• Port-53 DNS — direct resolver traffic (c-ares, aiodns, dig): the DNS packet head is shipped and the qname decoded from label format.
• nss-resolved varlink — glibc getaddrinfo on systemd hosts resolves over a unix socket, never touching port 53. The probe recognizes the varlink ResolveHostname JSON on tracked tasks' unix sends and lifts the name.

DoH/DoT are invisible — an agent resolving over its own HTTPS/TLS channel shows only as a :443 connect, not a domain. That's a real limit of watching from the kernel, documented rather than papered over.

Metrics

All labeled agent. A few carry an extra label — execs a comm (the tool that ran), net_connections a port, dns_queries a domain, and files_opened a path + mode — each capped per agent (then folded into other) to bound cardinality.

yeet_worker_up is prepended by the renderer: 0 means the scrape route is alive but the collector worker is not.

Setup

It works out of the box: the common agents — OpenClaw, Claude Code, Codex, Gemini, aider, opencode, goose, cline, continue, cursor, qwen, crush, amp, grok, omp, pi — are pre-filled in src/agents.txt, one comm prefix per line. Edit that file to change what's watched.

1. Install yeet and log in

curl -fsSL https://yeet.cx | sh    # installs the yeet CLI + the yeetd daemon
yeet login                         # authenticate this host
yeet status                        # must print "Status: Ok."

yeetd is the daemon the installer sets up; it does the eBPF loading and runs the service. Verify your environment anytime with make check.

2. Run the exporter

make up            # build + start the exporter on 127.0.0.1:9464 (no Docker)

That's the whole product — a Prometheus endpoint at http://127.0.0.1:9464/metrics (make metrics to eyeball it). make up is also how you pick up edits to src/ (it re-imports; the daemon copies unit scripts at import time). Stop it with make down.

3. Point Grafana at it

The exporter is a plain Prometheus endpoint, so add it to the Grafana + Prometheus you already run — no Docker. make wire prints both steps with absolute paths:

1. Prometheus — scrape the exporter. It binds 0.0.0.0:9464, so use 127.0.0.1 on the same host or the host's IP from a remote Prometheus (firewall the port if the box is network-reachable):

   scrape_configs:
     - job_name: agentcap
       static_configs:
         - targets: ["127.0.0.1:9464"]   # or "<host-ip>:9464" from elsewhere
   

2. Grafana — with a Prometheus datasource in place, import deploy/grafana/dashboards/agent-activity.json (Dashboards → New → Import); pick your datasource if its uid isn't prometheus. Re-import to update it later (regenerate first with make dashboard if you edited the generator).

No Grafana handy? make demo spins up a throwaway Prometheus + Grafana in Docker with the dashboard pre-loaded, at http://localhost:3000/d/agentcap/agent-activity. make down tears it back down. Docker is only needed for this.

The service (service.toml) is three units: keeper (eager) holds the collector shared worker — and the BPF probe and metric registry inside it — alive; scrape (lazy, per-connection) renders one exposition document per request over the console portal; web binds 0.0.0.0:9464 and mounts /metrics.

Changing the agent set

Edit src/agents.txt — one comm prefix per line, # comments and blank lines ignored — then make up. Or override for one run without editing anything:

make dev AGENTS=openclaw,claude,mybot   # standalone, live dump, no HTTP

Make targets

Lower-level pieces make up/demo build on: make deploy (import + start the service), make obs-up / make obs-down (just the Docker stack), and make start / stop / restart / remove (service lifecycle).

The dashboard

The Agent Activity dashboard (deploy/grafana/dashboards/agent-activity.json) is filterable by agent, with a stable color per agent across every panel. It has four sections:

• Overview — hero stats, tracked tasks, tool-exec rates, a "which agent ran what" table, top tools, CPU / network / file-I/O / churn timeseries.
• Audit — who talked to what — per-agent domain and destination-port tables (ports classified and color-coded: HTTPS/DNS green, SSH/SMTP amber, telnet/RDP red, unknown neutral), plus DNS and connection rates.
• Activity mix — CPU-share and egress-share donuts, a tool-launch bar chart, an active/idle state-timeline across agents, and per-agent CPU gauges — varied forms for a fast read.
• Agent detail — $agent — a repeated, collapsed row per selected agent with its own tools, lifecycle, CPU/tasks, network, domains and ports.

The dashboard is generated by deploy/grafana/gen-dashboard.py (edit the Python, rerun it, Grafana's file provider reloads within 30s) so the panel boilerplate and the per-agent color mapping stay consistent.

CI

• .github/workflows/ci.yml — BPF object builds, JS syntax, service.toml parses, promtool check config, dashboard JSON lint, compose config.
• .github/workflows/kernel-matrix.yml — boots 6.1 / 6.6 / 6.12 / bpf-next in VMs and runs veristat against bin/probe.bpf.o; a rejection on an old kernel is the signal of the minimum supported kernel (LSM + fexit programs need BTF and CONFIG_BPF_LSM). Same check locally: make veristat-matrix.

Layout

src/bpf/agentcap.bpf.c   the probe: sched tracepoints + LSM + fexit
src/agents.txt           the tracked agent list (one comm prefix per line)
src/agents.js            parses agents.txt into the prefix array
src/collector.js         shared worker: fills kernel maps, owns the
                         Telemetry registry, polls counters, serve()s scrapes
src/scrape.js            per-request /metrics renderer (console portal)
src/main.js              eager keeper — holds the worker (and probe) alive
service.toml             yeet service: units, web server, /metrics route
deploy/                  prometheus.yml, docker-compose, grafana provisioning
Makefile                 build + run lifecycle (make up, wire, demo, …)

Customization

The whole thing is a small yeet script — a BPF program (src/bpf/*.bpf.c), a JS collector (src/collector.js), and a generated dashboard (deploy/grafana/gen-dashboard.py). Each of these is a one- or two-file change, so point a coding agent at this repo and paste a prompt:

Watch a new agent

Add mybot as a new line in src/agents.txt and redeploy with make up. Then scrape http://127.0.0.1:9464/metrics and confirm agentcap_tasks{agent="mybot"} shows up while mybot is running. Leave the other agents' matching unchanged.

Alert on suspicious egress

Add a Grafana alert rule that fires when agentcap_net_connections_total records a destination port outside {80, 443, 53} for any agent. Include the agent and port labels in the notification text. Add the rule to the generated dashboard so it ships with the repo.

Map where agents connect (geomap)

Extend the BPF conn_event to include the destination IP, decode it in src/collector.js, and add a GeoIP lookup so each connect gets a country. Expose it as agentcap_connections_by_country_total{agent,country} and add a Grafana geomap panel in deploy/grafana/gen-dashboard.py. This should also surface DoH/DoT egress that has no visible domain.

Add a metric

Add a gauge agentcap_agents_total in src/collector.js counting agents with at least one live task, updated on the existing poll loop. Register it in the telemetry registry next to the others. Then add a stat tile for it in the dashboard generator and rerun make dashboard.

Restrict what's watched

Change the probe so it only tracks agents whose process is under a given systemd unit or cgroup, and add that as a metric label. Keep the comm-prefix matching from src/agents.txt as a second filter. Document the new option in the README's Setup section.

Ship it somewhere else

Add a second scrape route to service.toml that renders the registry as OpenMetrics or JSON instead of Prometheus text. Reuse the shared collector worker so it reports the same data. Update make wire to mention the new endpoint.

---

Built with yeet, a JS runtime for writing eBPF programs and live system dashboards on Linux. Join us on Discord.