How AgentSight observes AI agent sessions inside Docker

The short answer: move the session parser to the data, not the credentials to the host

The common container problem is simple to state. Claude Code, Codex, Gemini CLI, or Cursor may run in a dev container, so their native history and provider state live under that container's home directory. A host-side AgentSight Node cannot safely assume those files exist on the host, and copying provider credentials outward just to make a dashboard work would create a new secret-management path.

agentsight bind --docker-container NAME takes a different approach. The host launchesagentsight bridge with docker exec -i inside the selected running container. The bridge calls the existing native-session discovery and provider-message runtime there, then sends only structured list, get, and message results back to the host. The host merges those sessions into the same Node snapshot and session APIs used for local agent history.

# AgentSight must be available in both environments.
# Run the Node on the host and include one named container:
agentsight bind --docker-container ebpfos-dev

# More than one container is explicit and repeatable:
agentsight bind \
  --docker-container frontend-dev \
  --docker-container backend-dev

The protocol has only three operations

The current bridge protocol is intentionally small. Its Rust enum has three methods: sessions/list, session/get, and session/message. List returns native agent sessions discovered in the container. Get resolves one exact session. Message resumes a supported provider session through the same runtime AgentSight uses locally. There is no separate Claude-specific, Codex-specific, or Gemini-specific Docker RPC layer.

Bridge method	Runs inside the container	Host receives
`sessions/list`	Normal AgentSight native-session discovery	Bounded session metadata for the Node overview
`session/get`	Exact native-session lookup	One parsed session or a not-found/conflict/failure result
`session/message`	Existing provider resume/message runtime	Submission result and transport identity

This boundary matters for maintenance. Adding a provider to AgentSight's native-session runtime can make its sessions discoverable through the container bridge without inventing another Docker-specific parser. As of v1.0.30, the product documentation lists Claude Code, Codex, Gemini CLI, and Cursor discovery; resumable messaging covers Claude Code, Codex, and Gemini CLI, while Cursor remains observation-only.

Provider credentials stay in the container, but session content still crosses the pipe

The bridge source states its goal directly: manage sessions in a Docker container without copying provider credentials to the host. Provider authentication remains where the provider CLI expects it, and the host does not need a second Claude, Codex, or Gemini credential store for this path. The protocol itself carries parsed session records and user-submitted continuation messages rather than provider login material.

Credential locality is narrower than data locality. Session records can contain prompts, responses, model metadata, tool calls, paths, and other development evidence, and those parsed records are intentionally returned to the host Node so the browser can inspect them. Treat the host Node and browser access key as part of the trust path. “Credentials stay in the container” is a useful architecture property; it is not a claim that container session contents never leave the container.

The host reconstructs the container execution identity before starting the bridge

A dev container frequently runs its main process as root while the developer's agent state belongs to a non-root account such as vscode. Starting the bridge blindly as the image default user can therefore discover the wrong home directory or create files with the wrong ownership. AgentSight inspects the container and derives the bridge user, workdir, and home before it starts docker exec.

The preferred inputs are com.agentsight.user, com.agentsight.workspace, andcom.agentsight.home labels. Without those labels, the implementation falls back to the image configuration, absolute HOME, passwd data, or path ownership. Container paths are required to be absolute and normalized; parent-directory components are rejected. The resulting command uses Docker's normal --user, --workdir, and --env HOME=... exec options.

Bounded JSONL turns a long-lived exec process into a controlled transport

The implementation keeps one bridge process per configured container and exchanges newline-delimited JSON over its stdin/stdout. Several hard bounds keep this from becoming an unbounded in-process relay: a bridge frame is capped at 8 MiB, a bridge operation at 30 seconds, lock acquisition at one second, and Docker inspection/lookup commands at 10 seconds. A submitted message must contain 1 through 65,536 bytes.

These constants are implementation limits rather than provider limits. They make failures explicit and give the host a way to discard a broken bridge process after a failed or timed-out operation. If a future release changes them, the version-pinned source remains the right contract for a reproducible audit.

Multi-container lookup deliberately prefers an error over an arbitrary session

Once more than one container is configured, a short session identifier is no longer globally unique by assumption. AgentSight fans out lookup across the configured bridges. If the same session ID appears in more than one container, the request returns a conflict. More subtly, exact lookup also fails when one peer is unavailable even if another peer returned a match. The helper that combines results treats any peer error as an error instead of silently accepting the first successful answer.

That behavior is useful for provenance. A UI that guessed “first match wins” could resume the wrong coding agent after a container clone, restored workspace, or ID collision. Fail-closed lookup forces the operator to repair the ambiguous or unavailable source before a message is routed. After a session has been resolved, the message API includes the selected container and requires that container to remain configured.

A saved SQLite capture and a live Docker source are intentionally different modes

agentsight bind --db capture.db opens a saved, read-only capture. Docker-backed native sessions are live external sources that can support provider resume. The bind command rejects combining--db with --docker-container instead of presenting a mixed surface where some sessions are immutable artifacts and others accept messages. This keeps the session source model legible to both the operator and the UI.

For resumed Codex, the named container becomes the external sandbox boundary

The product documentation calls out one provider-specific consequence. When a Codex session is resumed through the Docker bridge, AgentSight treats the named container as the external sandbox boundary and disables Codex's nested command sandbox and interactive approvals for that turn. This avoids nested user-namespace failures common in locked-down development containers.

The operational consequence is direct: configure only containers whose filesystem and network authority are acceptable for the resumed agent. The container is doing real security work in that path. Local non-container sessions keep their existing defaults, so this is a boundary attached to the Docker-backed resume mode rather than a global Codex setting.

The named-container flag narrows AgentSight behavior, not Docker authority

The most important security distinction sits one layer below AgentSight. The host bridge controls Docker through the Docker CLI and daemon. Docker's own security documentation warns that users or credentials able to control the daemon can effectively obtain root-level authority on a conventional host. Docker group membership and daemon credentials should therefore be protected like administrative access.

Passing --docker-container ebpfos-dev tells AgentSight which container it is allowed to inspect and exec into; input validation also prevents names such as Docker options or path-like values from being interpreted as command-line control. That application-level allowlist does not reduce the underlying permissions already granted to the Docker client. If the host needs a narrower control plane, the product guide recommends a rootless per-user daemon or an allowlisting broker/socket proxy that exposes only the required inspect and exec operations.

Use this path for native agent history, not as a replacement for container system tracing

Docker-backed bindimports the agent's native session view. It answers questions such as which Claude/Codex/Gemini/Cursor sessions exist in the container, what their recorded conversation and tool history says, and whether a supported session can be resumed. It does not turn that native transcript into an independent record of every process, file, packet, or kernel event inside the container.

When the question is “what did the agent actually execute at the system boundary?”, use AgentSight's Linux record and tracing paths with the appropriate container/process scope. When the question is “show me the existing session state inside my dev container in the hosted UI without moving provider credentials to the host”, the Docker-backed bind bridge is the purpose-built path.

A practical deployment checklist

Keep the host and container AgentSight binaries on the same version. Install AgentSight in the running container, verify the intended developer user and home, then start the host Node with one explicit--docker-container per source. Confirm that duplicate session IDs return conflict rather than silently routing. If messaging is enabled, test it first on a bounded disposable task and verify which provider supports resume. Finally, review Docker socket access separately from AgentSight configuration; the two controls solve different problems.

# Inside the container
agentsight --version

# On the host
agentsight --version
docker inspect ebpfos-dev
agentsight bind --docker-container ebpfos-dev

# For a stricter host boundary, evaluate rootless Docker or an allowlisted broker
# before exposing daemon access to another service or user.

Source table and scope

This article is pinned to AgentSight v1.0.30 commit 934f441eff8ca210807333633f47b2efcb8cd020. Product behavior can move after this version, so source links below are fixed to the reviewed tree where possible. Docker behavior is described from Docker's own command and security documentation rather than inferred from AgentSight.

For the broader Node trust model, continue with AgentSight architecture and security and data handling. For retrospective codebase activity from existing native sessions, see the repository replay method.