How to record AI coding sessions in a Docker Sandbox

​

Overview

​

What It’s For

• Security policy on the session itself. Check that only sanctioned agents and models ran, that the agent reached only allowlisted MCP servers, that it ran no destructive commands, and that no secret leaked into a tool output. Chainloop ships built-in policies for each, and a failing one can block the merge.
• Cost and model usage. Token counts and estimated cost per session, attributable to a project, a feature, or a single pull request.
• A read on the contribution itself. Per-file AI-vs-human line attribution and an AI Session Score per run, so reviewers can tell which changes need a closer look — and, across many runs, which agents and models produce better work.

​

Get Started

​

Prerequisites

• Docker Sandboxes installed, with Docker running. Use sbx v0.42.0 or later — earlier versions record nothing without reporting an error, see Troubleshooting. On macOS:
  brew trust docker/tap
  brew install docker/tap/sbx
  sbx daemon restart                  # so the daemon matches the CLI
  
• A repository configured for Chainloop Trace. Run chainloop trace init in it once and commit what it writes — see Record your first session. The kit takes the organization, project, and workflow from that committed configuration.
• A Chainloop API token and an Anthropic token. Create the first with chainloop organization api-token create; the second is Claude Code’s own credential, supplied as a host-side secret (sbx secret set -g anthropic) or an interactive login inside the sandbox.

​

Launch the Sandbox

• Standalone
• Environment file

Run sbx run from the repository you want the agent to work in. The kit defines a complete sandbox environment rather than mixing into an existing one, so its reference goes in the positional slot, not behind --kit. The token is the only argument you need:

sbx run --clone \
  --kit-arg chainloopToken="$CHAINLOOP_TOKEN" \
  chainloop/sbx-kit-claude

--clone gives the sandbox a private clone of the repository, which per-file attribution needs. --kit-args-file reads the same arguments from a file, keeping the token out of your shell history.

An sbxenv.yaml at the repository root pins the setup for the whole team, so nobody has to remember the flags:

sbxenv.yaml

schemaVersion: "1"
name: chainloop-traced-claude

args:
  chainloopToken:
    default: ""
    description: Chainloop API token with access to the organization in .chainloop.yml.

agent: chainloop-trace-claude
kits:
  - source: chainloop/sbx-kit-claude
    args:
      chainloopToken: ${{ env.args.chainloopToken }}
      traceMode: persistent

workspace:
  path: .
  clone: true

agent: names what to run and kits: loads the artifact it comes from. traceMode: persistent makes a sandbox launched against a repository that was never initialized fail loudly.Launch it from the repository root, passing only the token:

sbx env run --env-arg chainloopToken="$CHAINLOOP_TOKEN"

Everyone then gets the same sandbox, and the configuration is reviewed like any other file in the repository.

​

Work as Usual

​

Troubleshooting and FAQ

sbx exec <sandbox> -- stat -c '%U:%G' /home/agent/.claude/projects

​

Current Limitations

• Scope the token to the organization it needs and rotate it like any other credential.
• Do not bind a Chainloop host to an sbx credential, for example with sbx secret set-custom --host api.cp.chainloop.dev. That flips the host to the intercepted path and silently stops attestation.

​

Further Reading

• How to record AI coding sessions — setting up chainloop trace, applying policies, and enforcing it
• AI Coding Sessions — what sessions are, how PR correlation works, and what each dashboard card means
• AI Session Score — per-PR confidence signal for AI-assisted changes
• Docker Sandboxes documentation — sandboxes, kits, and the sbx CLI