AgentSight

Prerequisites

• Linux kernel: 4.1+ with eBPF support (5.0+ recommended)
• sudo access: eBPF probes are auto-elevated; your agent stays unprivileged

For source builds, see docs/build.md.

Installation

Cargo or Release Binary

For local use, install with cargo install agentsight or download the latest release binary, then start with sudo agentsight top. Use the examples below when you want to record a specific command or inspect saved sessions.

Docker

Docker is useful for container, CI, or isolated Linux environments, but it still needs privileged host access for eBPF. See docs/docker.md.

Build from Source

Build requirements and source build commands live in docs/build.md.

Pin the binary explicitly if auto-discovery picks the wrong Node install

sudo ./agentsight record -c node --binary-path ~/.nvm/versions/node/v20.0.0/bin/node

> **Behind an HTTP/HTTPS proxy?** Traffic is still TLS-encrypted inside the
> Node process (the proxy only tunnels it), so AgentSight captures it the same
> way — at the `SSL_read`/`SSL_write` calls before encryption.

#### Monitoring Agents in Docker Containers (OpenClaw, etc.)

For an agent running inside a Docker container, pass the container to
`--binary-path` with the `docker://` scheme. AgentSight resolves the container's
process tree and attaches sslsniff to the right binary automatically:

Build debug versions with AddressSanitizer

make -C bpf debug ```

Quick Start

```bash cargo install agentsight

Usage

Usage Examples

Zero-Config: record

record is the simplest way to trace an agent. Put the command you want to run after record --; AgentSight handles everything else:

```bash

Web Interface

During a session, visit http://127.0.0.1:7395 for live traffic, process trees, and metrics: - Timeline View: http://127.0.0.1:7395/timeline - Process Tree: http://127.0.0.1:7395/tree - Raw Logs: http://127.0.0.1:7395/logs

Process tree visualization for agent subprocesses and file activity

Timeline visualization for LLM, process, file, and network events

Metrics visualization for memory and CPU usage

Gemini CLI runs on Node — record finds the right binary and traces it

sudo ./agentsight record -- gemini

With `record`, AgentSight now auto-discovers the Node binary from `-c node`
(it detects that Node embeds OpenSSL and attaches to the binary instead of a
system library), so this just works without `--binary-path`:

Monitor Gemini CLI or other Node.js AI tools — binary auto-discovered

sudo ./agentsight record -c node

Combined SSL and process monitoring with web interface

sudo ./agentsight debug trace --ssl true --process true --server true

Traditional Observability vs. System-Level Monitoring

Application-level tools such as LangSmith, Langfuse, and Phoenix are great for traces, prompts, tokens, evals, and latency when you own the application code. Gateway/proxy tools such as Helicone are useful when you can route provider traffic through a managed endpoint.

AgentSight focuses on the layer those tools often miss: what the agent actually does at the system boundary. It observes existing binaries and CLI agents without SDKs or proxies, then correlates LLM traffic with process execution, file access, and system activity.

AgentSight captures critical interactions that application-level tools miss:

• Subprocess executions that bypass instrumentation
• Plaintext LLM payloads at SSL/TLS call boundaries
• File operations and system resource access
• Cross-boundary behavior across LLM, process, and file events

❓ Frequently Asked Questions

Q: What permissions does AgentSight need? A: eBPF probes need root privileges, so AgentSight may prompt for sudo. With record -- <command> or stat -- <command>, the monitored agent still runs as your normal user; only the probes are elevated.

Q: What's the performance impact? A: Our evaluation reports less than 3% CPU overhead for typical traced agent workloads.

Q: Where does captured data go? A: record and stat -- <command> store sessions locally in SQLite by default. Use agentsight stat, agentsight top, agentsight report, agentsight list, agentsight db audit --json, and agentsight db token to inspect prior runs. Captured data can include prompts, responses, paths, headers, and network targets, so treat logs and DBs as sensitive.

Q: Why doesn't AgentSight capture traffic from Claude Code, Node.js, or Gemini CLI? A: These applications statically link their SSL library (BoringSSL for Claude/Bun, OpenSSL for all Node.js — both NVM and system installs) into their own binary instead of using system libssl.so, so there's nothing for sslsniff to hook by default. AgentSight handles this for you: record -- <command> always discovers the binary, and record -c node now auto-discovers the Node binary too. For Claude attach mode, pass --binary-path. See the "Zero-Config: record" and "Monitoring Node.js AI Tools" sections.

Q: What should I check if tracing fails? A: Verify you are on Linux with eBPF support, have sudo or CAP_BPF/CAP_SYS_ADMIN, and are using record -- <command> or the correct --binary-path for statically linked agents.