You want a coding agent to work on a repository, but not to read your SSH keys or call any host it likes. Docker gives you two command-line programs for that job, sbx and docker-agent. A Mac with Docker Desktop also has a third name, docker agent, and this section draws the line between all three.

When you finish this section, you can name the owner of each part of a sandboxed run and pick a launch path. You can also tell two agent binaries on one machine apart.

What sbx owns

Sandbox: a microVM that sbx creates for one agent. Each sandbox runs in a small microVM with its own Linux kernel, and it has a private Docker Engine. Inside m101-demo, the capture reads Linux 7.0.14 on Ubuntu 26.04.1 and Docker Engine 29.8.1 (the capture). The workspace appears at the same absolute path, and containers that the agent starts never show up in docker ps on your host.

sandboxd: the host daemon behind every local sbx command, reached at $HOME/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/sandboxd.sock (the capture). sbx runs without Docker Desktop and without Docker Engine. You do need a Docker sign-in with sbx login, and sbx diagnose reports it as Authentication — authenticated (the capture). Conflict C15 records why both claims hold.

The daemon also runs the proxy, and one of its two log categories is proxy. Every outbound TCP connection from the sandbox goes through a proxy on your host. On macOS, sbx secret set keeps each key in the system Keychain. The proxy adds the key to a request after the request leaves the VM, so the VM sees only the placeholder proxy-managed (the capture). The proxy and secrets take each one apart, and figure 1.1 shows who owns what.

$ sbx --help
Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker.
…
Sandbox Commands:
…
  create      Create a sandbox for an agent
  exec        Execute a command inside a sandbox
…
  run         Run an agent in a sandbox
…
Management Commands:
  daemon      Manage sandboxd daemon
  diagnose    Diagnose common issues with your sbx installation
  mcp         Manage MCP servers
  policy      Manage sandbox policies
…
  secret      Manage stored secrets
…

The agents sbx runs

sbx run accepts eleven agent names: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, and shell. sbx create has eight of them as subcommands and leaves out copilot, droid, and kiro. Those three moved to public kits, and since v0.43.0 you can start them by name again. sbx create docker-agent also answers to the alias cagent. shell gives you a Bash login shell in a sandbox, with no agent binary installed. Conflict C9 lists the shorter agent lists in older posts.

What docker-agent owns

Agent file: a YAML file that names agents, their models, their toolsets, and the rules between them. Docker Agent is an open-source framework for teams of specialized AI agents. Its run command drives the loop: a model call, the tool calls the model asks for, and the sub-agents it delegates to. The agent loop lesson explains that loop, and Part 6 serves and shares the same file.

The docker-agent binary isolates nothing by itself. On the host, its shell toolset runs commands "in the user's environment" (the capture).

$ docker-agent --help
Docker AI Agent Runner.
…
Core Commands:
  getting-started Learn docker agent with a hands-on interactive tour
  run             Run an agent
  setup           Interactively set up a model (built-in provider, local, custom endpoint, or Claude Code)
  share           Share agents
…
Advanced Commands:
…
  eval            Run evaluations for an agent
…
  sandbox         Manage docker-agent sandbox settings
  serve           Start an agent as a server
  sessions        Inspect recorded sessions
…

Two launch paths

sbx run docker-agent ~/my-project starts from sbx. The sandbox uses docker/sandbox-templates:docker-agent and runs docker-agent run --yolo when you pass no arguments. Only project-level configuration in the workspace reaches it.

docker-agent run --sandbox agent.yaml starts from your agent file. Here docker-agent drives the sbx CLI that you installed, and --template defaults to docker/docker-agent-sbx-templates:latest. Two paths use two images, as conflict C61 rules. The capture kit recorded only the second path, and the next section follows it.

Two agent binaries on one machine

Docker Desktop 4.94.0 bundles Docker Agent v1.144.0 as the CLI plugin docker agent. Homebrew installs v1.149.0 as docker-agent, and the docs say that it also works as a standalone binary.

$ docker agent version
docker agent version v1.144.0
Commit: 3873760f47ecf22f72f65bd776c056a337d6f35c
[exit 0]

$ docker-agent version
docker-agent version v1.149.0
Commit: Homebrew
[exit 0]

The hints that v1.149.0 prints still say docker agent sandbox allow <host> (the capture), and on this Mac that command runs v1.144.0. This manual writes docker-agent in every command and pins v1.149.0, as conflict C48 rules. A third build runs inside the sandbox template, as the next section shows.

The same plugin list holds sandbox v0.13.0, and docker sandbox prints only its removal notice (the capture). The migration section maps its commands. The list also holds ai v1.31.0, the plugin behind docker ai, which the docs call Gordon, the AI assistant built into Docker. Gordon is outside this manual.

You have an agent file with the filesystem and shell toolsets, and its model is ai/qwen3:4b on Docker Model Runner on your Mac. On the host, shell runs with your permissions. --sandbox moves the tools into a microVM and leaves the model on the host.

This section follows the recorded run, step by step, and figure 1.3 draws it. When you finish this section, you can read the launch summary of a sandboxed run and explain the two failures this run met.

The agent file

The agent file differs from the host version only in its provider. The 127.0.0.1 of your host cannot be reached from inside the sandbox, so the provider points at host.docker.internal:

version: "16"

providers:
  host-runner:
    provider: dmr
    base_url: http://host.docker.internal:12434/engines/llama.cpp/v1

models:
  local:
    provider: host-runner
    model: ai/qwen3:4b
    temperature: 0
…

Step 1: allow the model host

Persistent allowlist: the hosts that docker-agent sandbox allow stores, which docker-agent adds to the allow rules of the sandbox proxy on every later --sandbox run. The help names it the fix for a Blocked by network policy 403. The proxy translates host.docker.internal to localhost, so the capture allows localhost:12434 before the run:

$ docker-agent sandbox allow localhost:12434  (--config-dir, --data-dir, --cache-dir under fixtures/repo-sandbox/.m101, inside the workspace)
…
Added 1 host(s) to the persistent sandbox allowlist:
  + localhost:12434
[exit 0]
…

Step 2: keep the state directories in the workspace

The capture kit keeps docker-agent out of ~/.cagent with --data-dir, --cache-dir, and --config-dir. With --sandbox, a data directory outside the workspace is refused, and the help gives only the default, ~/.cagent. The capture kit therefore puts all three under .m101/ in the workspace:

…
Error: --data-dir must be inside the sandbox's writable workspace $CAPTURE/fixtures/repo-sandbox
[exit 1]

Step 3: the launch summary

…
Models gateway: none configured
Models catalog: allowlisting models.dev in the sandbox proxy
User sandbox allowlist: allowlisting 1 host(s) from `docker agent sandbox allow`:
  - localhost:12434

sandbox    docker-agent-<hash>
agent      docker-agent
workspace  $CAPTURE/fixtures/repo-sandbox (rw)
           $CAPTURE/fixtures/agents (ro)
           $CAPTURE/fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash> (ro)
           $CAPTURE/fixtures/repo-sandbox/.m101/cfg (ro)
image      docker/docker-agent-sbx-templates:latest
cpu        10
memory     32 GiB
…
✓ Created sandbox docker-agent-<hash>

The run set no --models-gateway. It allows models.dev, because without that host the first catalog lookup fails with 403 Blocked by network policy. The next line repeats the host from step 1.

Auto-kit: a directory that docker-agent stages on the host and mounts read-only into the VM at the same path. Here it is .m101/cache/sandbox-kits/<hash>, and its manifest.json holds only agent_ref and built_at (the capture). The workspace is read-write, and the agent file's directory, the kit, and the config directory are read-only.

Step 4: an ordinary sandbox

During the run, sbx ls lists docker-agent-<hash> with the agent docker-agent, the status running, and the same four workspaces, three of them :ro (the capture). The sandbox is an ordinary one, and sbx lists and removes it like any other.

Step 5: the session store fails

Inside the VM, the run stopped before any model call:

…
Error: creating session store: migration failed even after database reset: failed to create migrations table: attempt to write a readonly database (1032)
Error: 
[exit 1]

The data directory sits on the virtiofs workspace mount, which mount lists as rw. A Python sqlite3 write on the same mount fails the same way (the capture), so on this host SQLite cannot write through that mount. The run printed no safety mode, so conflict C62 stays open. Docker Agent exits, but it does not stop or remove the sandbox VM, and the VM stayed running.

Step 6: the model call from inside

docker-agent version main
Commit: 154b78f2d517dae1397866dfb7586c4a302a3151
…
ANTHROPIC_API_KEY=proxy-managed
…
HTTP_PROXY=http://gateway.docker.internal:3128
…
NO_PROXY=localhost,127.0.0.1,::1,gateway.docker.internal
OPENAI_API_KEY=proxy-managed
…
Persistent sandbox allowlist is empty.

The template runs docker-agent version main, not v1.149.0, although the docs say that :latest is built from the most recent v* release. The provider keys read proxy-managed. The in-VM allowlist is empty, because the allowed hosts arrive as proxy rules from the host.

The capture then starts the same agent file inside the VM by hand, with its state in /tmp/m101. This run shows the model path from the VM, not a working --sandbox launch:

$ sbx exec docker-agent-<hash> sh -c 'docker-agent --config-dir /tmp/m101 --data-dir /tmp/m101 --cache-dir /tmp/m101 run --exec --last …
…
The working directory contains README.md with 1 line.
[exit 0]

The request to host.docker.internal:12434 leaves through HTTP_PROXY, because that host is not in NO_PROXY. The sandbox proxy changes host.docker.internal to localhost before it forwards the request, and the rule from step 1 admits it. The answer is correct: the capture kit copies the same README into every workspace, and it holds the one line hello (the capture).

Step 7: remove the sandbox

$ sbx rm --force docker-agent-<hash>
Deleting sandbox docker-agent-<hash>...
Sandbox 'docker-agent-<hash>' removed
[exit 0]

A later run from the same workspace reuses the VM, and creates a new one only when the set of mounts has changed.

You have a repository with two commits and a README, and you want a shell agent to work on it and on nothing else. The capture does that with sbx create shell $CAPTURE/fixtures/repo --name m101-demo, where $CAPTURE stands for the capture directory, and the rest of this part reuses that sandbox. When you finish this section, you can name the verb that creates, attaches, stops, removes, or prunes a sandbox, and what each one keeps.

The agent and the workspace

Agent: the first positional argument of sbx run and sbx create: either a built-in agent name or a reference to a sandbox kit. The built-in names are claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, and shell. A kit reference is a directory, a ZIP file, a git repository, or an OCI reference. A relative path must be explicit, such as ./my-kit or ../my-kit.zip. So sbx run my-kit looks for an agent called my-kit, and sbx run ./my-kit reads a kit, as the kit descriptor explains.

Workspace: the directory after the agent, mounted inside the microVM at the same absolute path. Inside m101-demo, pwd prints $CAPTURE/fixtures/repo, and mount lists that path as a virtiofs mount. sbx run mounts the current directory when you give no path. sbx create without a path makes a sandbox with no mount.

There the agent works in the filesystem of the container instead of on your files. Extra paths follow the first one, and :ro mounts one of them read-only. A read-only argument can name a single file. That keeps one path out of reach in a workspace that the sandbox can otherwise write.

$ sbx create shell $CAPTURE/fixtures/repo --name m101-demo

sandbox    m101-demo
agent      shell
workspace  $CAPTURE/fixtures/repo (rw)
image      docker/sandbox-templates:shell-docker
cpu        10
memory     32 GiB

Pulling image
  <layers>
✓ Image ready
✓ Created sandbox m101-demo

To connect to this sandbox, run:
  sbx run --name m101-demo
[exit 0]

$ sbx exec m101-demo sh -c 'pwd; echo; ls -la; echo; cat README.md; echo; git log --oneline'
$CAPTURE/fixtures/repo
…
c7dfd56 second
086df68 first
[exit 0]

Names and re-attach

Name: the key of a sandbox in every later command, by default <agent>-<workdir>, the agent name and the workspace directory name. A name has at least two characters and starts with a letter or a number. It contains only letters, numbers, hyphens, and periods, and --cloud rejects periods. The name default is reserved. Since v0.43.0 the daemon also rejects a name that is longer than 63 characters or that ends in a hyphen or a period. The 2025 plugin allowed _ and + in a name, and conflict C25 records the change.

Two sandboxes can share one workspace. The capture creates m101-demo-2 on the same fixtures/repo, and sbx ls --json lists both as running. A blog post of 2026-03-11 said that Docker enforces one sandbox per workspace. A talk of 2026-08-13 runs claude and codex on one workspace in two terminals, and S27 rules that the names decide.

--name on sbx run re-attaches to an existing sandbox, and then you can leave out the agent. sbx run reads it from the spec of the existing sandbox. Give the agent too, and sbx run checks it against the stored one. sbx create prints that re-attach command at the end of its output.

{
  "sandboxes": [
    {
      "name": "m101-demo",
      …
      "status": "running",
      …
      "workspaces": [
        "$CAPTURE/fixtures/repo"
      ],
      …
    },
    {
      "name": "m101-demo-2",
      …
      "status": "running",
      …
      "workspaces": [
        "$CAPTURE/fixtures/repo"
      ],
      …
    }
  ]
}

What is fixed at creation

Some flags act on every attach, and most act once, when the sandbox is created. A re-attach with a different -p or --skills changes nothing, and the help says so flag by flag.

The recording Mac gave m101-demo cpu 10 and memory 32 GiB, the upper bound of the memory clamp. --rm does not work together with --detached, because a detached run has no session to end.

stop, rm, and prune

sbx stop keeps the sandbox and ends its microVM. The capture prints state preserved with the restart command. The docs list what persists across a stop and a restart. That is the installed packages, the Docker images, the configuration changes, the command history, and the workspace files that are not on a mount. The daemon also stops a sandbox on its own. After the capture closed its last session and waited, sbx ls showed m101-demo as stopped, and daemon.log gives the reason.

$ grep auto-stop daemon.log | grep m101-demo | tail -2
{"time":"<ts>","level":"INFO","msg":"auto-stop grace period expired, stopping runtime","version":"v0.47.0 0411f50ee4700fe7bd37e6e7e3aced563e850ca9","runtime":"m101-demo"}
{"time":"<ts>","level":"INFO","msg":"auto-stopped runtime after last session disconnected","version":"v0.47.0 0411f50ee4700fe7bd37e6e7e3aced563e850ca9","runtime":"m101-demo"}

sbx run -d against an existing sandbox keeps it running after the sessions disconnect, until you stop or remove it. A kit can declare com.docker.sandbox/long-running@1 for the same effect, as the capabilities show.

sbx rm is the opposite of stop. For a local sandbox it stops the sandbox, removes its containers, and cleans up its Git worktrees. It also deletes the state and the secrets of that sandbox. --force skips the prompt and removes a sandbox with an open SSH connection, and --all removes every local sandbox.

sbx prune removes stopped sandboxes only, because prune never removes a running sandbox. --filter until=168h keeps anything stopped within the last week, and a sandbox whose stop time the daemon cannot report is left alone. --dry-run --json shows both sets before you commit.

{
  "would_remove": [
    {
      "name": "m101-demo-2",
      "agent": "shell",
      "stopped_at": "<ts>",
      "workspaces": [
        "$CAPTURE/fixtures/repo"
      ]
    }
  ],
  "skipped_unknown_stop": []
}

$ sbx prune --force
Deleting sandbox m101-demo...
Sandbox 'm101-demo' removed
Deleting sandbox m101-demo-2...
Sandbox 'm101-demo-2' removed
[exit 0]

$ sbx ls --json
{
  "sandboxes": []
}
[exit 0]

Both rm and prune delete the secrets scoped to the sandbox, which sbx secret explains. Figure 2.1 puts the verbs on the edges of one state machine.

A server inside m101-demo listens on port 8080. From the host you want to open it, copy a file in, and read a result out. docker exec, docker cp, and docker run -p do those jobs for a container, and sbx has the same three verbs with a changed rule in each. When you finish this section, you can run a command as any user, copy a file either way, and publish a port that localhost reaches.

sbx exec

exec: sbx exec [flags] SANDBOX COMMAND [ARG...] runs one command inside the sandbox, and it starts a stopped sandbox first. The flags follow docker exec, but detached exec with -d or --detach is not supported, so -d appears in the help only to say so. The 2025 plugin ran docker sandbox exec -d detached, which conflict C31 records. With --cloud, sbx exec rejects the flags -d, --user, and --privileged instead of ignoring them.

The command runs as the agent user, uid 1000, with the sudo and docker groups, in the workspace directory. -u root runs it as root, which the help shows for apt-get update and the capture uses to create /opt/marker-from-demo. -w sets another working directory, -e KEY=VALUE and --env-file FILE set variables for that one command, and -it opens a shell.

Inside, a sandbox knows its own name. Since v0.39.0 a sandbox gives its own identity in the environment variables SANDBOX_NAME and SANDBOX_ID, and SANDBOX_VM_ID stays as a deprecated copy of the name. WORKSPACE_DIR names the mount, and HOME is /home/agent.

$ sbx exec m101-demo sh -c 'env | sort'
…
HOME=/home/agent
…
PWD=$CAPTURE/fixtures/repo
…
SANDBOX_ID=<uuid>
SANDBOX_NAME=m101-demo
SANDBOX_VM_ID=m101-demo
…
WORKSPACE_DIR=$CAPTURE/fixtures/repo
…
[exit 0]

sbx cp

cp: sbx cp SRC DST, where one side is a sandbox path written as SANDBOX:PATH and the other side is a host path. A copy from one sandbox to another is not supported. The capture's sbx cp m101-demo:/tmp/out.txt m101-demo-2:/tmp/x exits 1 with that message, so route such a copy through the host. A directory copy places the directory itself at the destination. When the destination is an existing directory, the source goes inside it, and -L follows symbolic links in the source. The sandbox path is a container path, so /tmp/in.txt in the capture sits outside the workspace mount and is deleted with the sandbox.

The one rule with a security history is copy-out. Release v0.38.0, published 2026-08-06, fixed a flaw that let a copy-out with sbx cp escape its destination. The flaw is CVE-2026-17106.

$ sbx cp $CAPTURE/work/in.txt m101-demo:/tmp/in.txt
[exit 0]

$ sbx exec m101-demo sh -c 'cat /tmp/in.txt; printf out > /tmp/out.txt'
in
[exit 0]

$ sbx cp m101-demo:/tmp/out.txt $CAPTURE/work/out.txt
[exit 0]

$ cat $CAPTURE/work/out.txt
out
[exit 0]

$ sbx cp m101-demo:/tmp/out.txt m101-demo-2:/tmp/x
error: copying between sandboxes is not supported
  try: sbx cp --help
[exit 1]

sbx ports

ports: sbx ports SANDBOX lists the published ports, --publish SPEC adds one, and --unpublish SPEC removes one. The spec is [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL], and without a HOST_PORT the daemon picks a free port. Publishing starts a stopped sandbox before it creates the host binding, as exec does.

The rule to learn is the address family. Without a PROTOCOL, publishing uses tcp4, so the host binding is 127.0.0.1 alone. To bind both families, publish tcp explicitly. This changed in v0.42.0: a published port no longer listens on ::1 unless you name the protocol. The 2025 plugin bound both loopbacks, as conflict C39 records.

The capture publishes 18081:8080, gets 127.0.0.1:18081 -> 8080/tcp4, and curl answers 200 on 127.0.0.1 and fails with exit 7 on ::1.

$ sbx ports m101-demo --publish 18081:8080
Published 127.0.0.1:18081 -> 8080/tcp4
[exit 0]

$ sbx ports m101-demo
HOST IP     HOST PORT   SANDBOX PORT   PROTOCOL
127.0.0.1   18081       8080           tcp4
[exit 0]

$ curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18081/README.md
200
[exit 0]

$ curl -sS -o /dev/null -w '%{http_code}\n' 'http://[::1]:18081/README.md'
curl: (7) Failed to connect to ::1 port 18081 after <n> ms: Couldn't connect to server
000
[exit 7]

--publish 8080/tcp then binds both families, each on an ephemeral host port, and sbx ports --json lists every binding as host_ip, host_port, sandbox_port, and protocol.

$ sbx ports m101-demo --publish 8080/tcp
Published 127.0.0.1:<port> -> 8080/tcp
Published [::1]:<port> -> 8080/tcp
[exit 0]

$ sbx ports m101-demo --json
…
  {
    "host_ip": "::1",
    "host_port": "<port>",
    "sandbox_port": 8080,
    "protocol": "tcp"
  }
]
[exit 0]

Unpublish without a protocol removes the mapping in both cases: published with the same default, or published as dual-stack tcp. The capture ends with sbx ports m101-demo --json printing []. -p on sbx run applies at creation only, so change ports later with sbx ports. sbx ls prints the bindings in its PORTS column, as 127.0.0.1:18081->8080/tcp4 in the capture. In the cloud a published port gets a public URL and UDP is refused, as sbx --cloud shows.

You spent an hour inside m101-demo installing a toolchain, and tomorrow a second sandbox needs the same tools without the hour. The capture leaves a marker file at /opt/marker-from-demo, saves the sandbox as m101-tpl:v1, and creates m101-from-tpl from it. When you finish this section, you can save a template, start a sandbox from it, and carry it to another host as a tar.

What a template holds

Template: a saved snapshot of a sandbox's container filesystem, stored as an image. You create new sandboxes from it with sbx run --pull never -t TAG AGENT [WORKSPACE]. The docs draw the line between image and kit. A template holds image content, and the agent kit still supplies the runtime settings, such as credentials and network rules. Mounted filesystems are not in it, because a saved template is not a backup of the whole sandbox.

That excludes host workspaces and the Docker store at /var/lib/docker. Everything else in the container filesystem is in it, including any key an agent wrote to a file. Keep credentials in sbx secret and the proxy instead. Agent configuration files such as /home/agent/.claude/settings.json are written again every time a sandbox is created, so a change there does not survive either.

Every built-in agent starts from docker/sandbox-templates:<variant>, and m101-demo pulled docker/sandbox-templates:shell-docker. A variant with a -docker suffix includes Docker Engine, so you can build and run containers inside the sandbox. That is why docker version answers inside m101-demo. With platform.images.useDHI set, the default template docker/sandbox-templates:claude-code-docker changes to dhi/sbx-templates:claude-code-docker, and the tag stays the same.

sbx template save

sbx template save SANDBOX TAG needs a stopped sandbox. The capture tries it on the running m101-demo, reads cannot save a running sandbox, stops it, and saves m101-tpl:v1. The image goes to the image store of the sandbox runtime. That store is separate from the image store of the Docker daemon on the host. The 2025 plugin's docker sandbox save loaded the image into the host daemon by default, and --output was the way to a file, as conflict C32 records.

$ sbx template save m101-demo m101-tpl:v1 --output $CAPTURE/work/m101-tpl.tar
Sandbox m101-demo is running and must be stopped before saving. Stop it now? (y/N): error: cannot save a running sandbox; stop it first with:
  try: sbx stop m101-demo
[exit 1]

$ sbx stop m101-demo
Sandbox 'm101-demo' stopped; state preserved. Restart with: sbx run --name m101-demo
[exit 0]

$ sbx template save m101-demo m101-tpl:v1 --output $CAPTURE/work/m101-tpl.tar
Snapshotting image in sandbox ...
Exporting image to $CAPTURE/work/m101-tpl.tar ...
Exported to $CAPTURE/work/m101-tpl.tar

Save complete. To use the image as a template:
    sbx run --pull never -t docker.io/library/m101-tpl:v1 AGENT [WORKSPACE]
[exit 0]

sbx template ls --json then lists three images: the base docker.io/docker/sandbox-templates:shell-docker, the new docker.io/library/m101-tpl:v1 with flavor shell, and docker.io/sandboxes-swap/m101-demo:bf19e491. The last one is an image the runtime keeps for the stopped sandbox, and it is gone once every sandbox is removed. Each record has id, repository, tag, flavor, created_at, and size, and the capture masks the id, so this manual does not state its format.

{
  "images": [
    …
    {
      "id": "<id>",
      "repository": "docker.io/library/m101-tpl",
      "tag": "v1",
      "flavor": "shell",
      "created_at": "<ts>",
      "size": "<n>"
    },
    …
  ]
}

Reuse with --pull never -t

Reuse is sbx run --pull never -t TAG AGENT [WORKSPACE], and the help explains the flag: --pull never uses the saved image and does not try a registry. The capture uses sbx create --pull never -t m101-tpl:v1 shell --name m101-from-tpl, reads Checking image instead of Pulling image, and finds /opt/marker-from-demo inside the new sandbox. Name the agent that the template was built for. A Claude template run with codex prints a warning that the sandbox can fail to work correctly.

$ sbx create --pull never -t m101-tpl:v1 shell --name m101-from-tpl

sandbox    m101-from-tpl
agent      shell
workspace  none · no workspace bind mount
image      m101-tpl:v1
cpu        10
memory     32 GiB

Checking image
✓ Image ready
✓ Created sandbox m101-from-tpl
…
$ sbx exec m101-from-tpl sh -c 'ls -l /opt/marker-from-demo'
-rw-r--r-- 1 root root 0 <date> /opt/marker-from-demo
[exit 0]

sbx template inspect works only in the cloud in v1, and it needs --cloud. The local attempt in the capture exits 1 with a hint to run docker image inspect -- m101-tpl:v1. That command reads the host daemon's store, which the runtime does not share, so use sbx template ls for a local template. sbx template rm m101-tpl:v1 --force prints Removed: m101-tpl:v1, and sbx reset clears the cached images too.

Export and load

--output FILE on save also writes a tar. work/m101-tpl.tar has 24 entries and starts with blobs/sha256/, the layout of an OCI image. On the other host, sbx template load FILE loads the image from the tar file into the image store of the sandbox runtime, and sbx run --pull never -t m101-tpl:v1 shell starts from it. The capture did not load the tar on a second machine, so figure 2.2 draws that step from the help text. The same path imports an image that you built yourself: docker image save writes the tar, and sbx template load imports it. So no registry needs to serve the image when the sandbox is created.

In the cloud, sbx --cloud template load FILE NAME needs --cpus and --memory-mib that together name a billable shape. The shapes run from micro, 1 vCPU and 2048 MiB, to xl, 16 vCPU and 32768 MiB. --capture-mode all adds memory and a microVM checkpoint to the disk capture. Tier C was not recorded, so this manual shows no cloud listing, and sbx --cloud cites the help text instead.

sbx ls hangs, or a command fails with ensure daemon: daemon exited unexpectedly, and you need to know which process answers, where it writes, and how to start over. Every verb in this part talks to one host daemon, sandboxd, over a Unix socket. When you finish this section, you can find the socket and the log, read the thirteen checks of sbx diagnose, and say what sbx reset deletes.

sandboxd

sandboxd: the host daemon behind every local sbx verb, managed with sbx daemon start, stop, restart, status, and log-level set. The settings commands use the local daemon to read evaluated values and manage overrides, and they start it when it is not running. So the first probe of sbx settings list printed Starting sandboxd daemon... before its table. sbx daemon start -d runs it in the background. --policy allow-all, balanced, or deny-all initializes the global network policy at the same time, which sbx policy init covers. sbx daemon log-level set TARGET LEVEL changes one log category, proxy, general, or all.

sbx daemon status --json names the socket and the log, both under ~/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/ on the recording Mac, where $HOME is a capture mask.

{
  "status": "running",
  "socket": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/sandboxd.sock",
  "logs": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/daemon.log"
}

The log is JSON lines with time, level, msg, version, and often a runtime, the sandbox name, and the lifecycle section reads two of them. Since v0.43.0 the local daemon checks the operating-system user of each connection on Unix sockets and Windows named pipes. Since v0.46.0 a second daemon on a state directory that is in use fails with an error and leaves the running daemon alone.

The state directory

State directory: the tree where sandboxd keeps sandboxes, images, policies, and its socket. On macOS it is ~/Library/Application Support/com.docker.sandboxes/, on Windows %LOCALAPPDATA%\DockerSandboxes, and on Linux the state is in three directories: ~/.local/state/sandboxes/, ~/.cache/sandboxes/, and ~/.config/sandboxes/. Release v0.29.0 added the SANDBOXES_STORAGE_ROOT override, and v0.31.0 moved the state directory symlink from /tmp to ~/.sbx/run/. The daemon binds its containerd socket under that symlink. The sbx kit builder history help pages, captured in a shell that could not bind sockets, end in failed to create unix socket on $HOME/.sbx/run/d/containerd/containerd.sock.ttrpc.

Two more trees matter. The first is the shared skills store at sandboxes/agent-skills under the state directory. The second is the audit log under ~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/, where each file is named audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl. The 2025 plugin kept its VMs under ~/.docker/sandboxes/vm/ and its images under ~/.docker/sandboxes/image-cache/, which the migration section maps. Figure 2.3 draws the macOS tree, and the settings table lists every path for the three systems.

sbx diagnose

sbx diagnose runs thirteen checks in four groups and prints a pass, a warning, or a failure for each. Installation finds the binary, its version, the daemon, and a diagnostics bundle. Platform confirms kern.hv_support is 1 and finds mkfs.erofs with its default block size and the guest kernel page size. Storage checks the state directory, its permissions, and the free space. Connection checks the version match, the socket, the SSH client config, and the sign-in.

The page-size check exists because v0.43.0 made diagnose warn when its default block size is larger than the page size of the sandbox kernel. On the recording Mac the block size is 4096 bytes and the guest page size is 16384 bytes, which getconf PAGESIZE inside m101-demo confirms.

{
  "version": "1.0",
  "checks": [
    …
    {
      "name": "Virtualization",
      "status": "pass",
      "message": "supported",
      "detail": "kern.hv_support is 1",
      "hint": ""
    },
    {
      "name": "mkfs.erofs",
      "status": "pass",
      "message": "found",
      "detail": "/opt/homebrew/Caskroom/sbx/0.47.0/Sbx.app/Contents/libexec/mkfs.erofs, default block size <n> bytes, guest kernel page size <n> bytes",
      "hint": ""
    },
    …
  ],
  "summary": {
    "pass": 13,
    "warn": 0,
    "fail": 0,
    "skip": 0
  }
}

--json gives a version, a checks array with name, status, message, detail, and hint, and a summary with pass, warn, fail, and skip counts. -o github-issue formats the same report for a bug report, and --upload sends a bundle to Docker support. diagnostics.autoUpload in sbx settings list is the consent for automatic uploads.

sbx reset

sbx reset returns the install to a freshly installed state, and the help lists the steps:

• stop running sandboxes, with a 30 s timeout
• clear the image cache and the internal registries
• delete all sandbox state and all policies
• remove the managed SSH configuration
• clear the sessions and the history of the Gordon assistant
• delete stored secrets, unless --preserve-secrets
• sign out, stop the daemon, and remove the state, cache, and config directories

The docs give Gordon no role in a sandbox, so this manual repeats that one item and claims nothing more, as conflict C33 rules. The docs use the command after an upgrade. A newer sbx can move the local database to a schema that older binaries cannot read. Then --preserve-secrets keeps your secrets through that.

The last resort is to delete the state directory by hand after sbx reset. Your workspaces stay where they are. The docs say that host workspace files stay on your host when a sandbox is removed, and sbx reset lists only state, cache, and config directories. Commands that help text names but the help tree does not list, such as sbx mount, are collected in sbx settings list.

Your company routes every connection through a proxy, and your first sbx run cannot pull a template. The fix is a setting, proxy. The questions are where to set it, whether the daemon must restart, and which value wins when an environment variable disagrees. When you finish this section, you can read one record of sbx settings list --json, change a setting, and know when sbx daemon restart is needed.

One record

Setting: a key such as proxy with a type, a default, an evaluated value, and a source. sbx settings list --json printed 31 records on the recording Mac, each with key, type, default, value, source, and description, and some with env_var or requires_restart. The source is one of three values: default, envvar, or override. The type is bool, int, float, string, or json, and sbx settings set KEY VALUE parses the value by that type. Thirteen of the 31 keys have no env_var, among them proxy, mcp.forceLocalGateway, and skills.defaultMode, so the environment cannot set them and only an override can.

[
  …
  {
    "default": [
      {
        "identityRegexp": "^.*@docker\\.com$",
        "issuer": "https://accounts.google.com"
      }
    ],
    "description": "JSON array of trusted signer policies (key-based {\"key\":path} or keyless {\"issuer\":...,\"identity\":...}). Defaults to Docker employee identities (*@docker.com via https://accounts.google.com).",
    "env_var": "DOCKER_SANDBOXES_KIT_TRUSTED_SIGNERS",
    "key": "kit.trustedSigners",
    "source": "default",
    "type": "json",
    …
  },
  …
  {
    "default": "",
    "description": "Upstream proxy for sandbox, daemon, and supported CLI host egress (URL, PAC source, \"system\", or \"direct\"; empty = automatic: HTTP(S)_PROXY if set, otherwise the host OS proxy).",
    "key": "proxy",
    "requires_restart": true,
    "source": "default",
    "type": "string",
    "value": ""
  },
  …
  {
    "default": "",
    "description": "Upstream proxy for sandbox egress only (overrides proxy).",
    "env_var": "DOCKER_SANDBOXES_PROXY",
    "key": "proxy.sandbox",
    "requires_restart": true,
    "source": "default",
    "type": "string",
    "value": ""
  },
  …
  {
    "default": "readonly",
    "description": "Default for an omitted --skills flag or sbx.yaml `skills:` key: \"off\", \"readonly\", or \"readwrite\". Applies to sandboxes created after the change; existing sandboxes' mounts are never retroactively changed.",
    "key": "skills.defaultMode",
    "source": "default",
    "type": "string",
    "value": "readonly"
  },
  …
  {
    "default": "shell",
    "description": "Built-in agent used for SSH auto-created sandboxes.",
    "env_var": "DOCKER_SANDBOXES_SSH_DEFAULT_AGENT",
    "key": "ssh.defaultAgent",
    "requires_restart": true,
    "source": "default",
    "type": "string",
    "value": "shell"
  },
  …
]

The proxy record shows the shape of a value. It takes a URL, a PAC source, system, or direct, and an empty string means automatic: HTTP(S)_PROXY if set, otherwise the host OS proxy. proxy.sandbox narrows that to sandbox egress only, and it is the one with an environment alias, DOCKER_SANDBOXES_PROXY.

Precedence and restart

An environment variable wins over a user override, so an exported DOCKER_SANDBOXES_PROXY beats sbx settings set proxy.sandbox. Above both sits the organization. Administrator constraints also apply to saved overrides, and the daemon rejects a value that conflicts with them. sbx settings unset KEY removes the override, and the administrator policy stays in effect. After that, the value comes from the environment variable, a remote default, or the built-in default. The remote default is a fourth origin that the SOURCE column does not name.

Most changes take effect within about five seconds, and the rest need sbx daemon restart. The table marks them in its RESTART column, and its footer says who needs the restart.

Some fields were truncated; use --no-trunc or --json to see them in full.

RESTART=yes: existing daemon-side consumers require `sbx daemon restart`. Supported CLI clients and new sandboxes use their current proxy settings immediately.

Fifteen keys carry "requires_restart": true on the recording Mac: the four proxy* keys, the three no_proxy* keys, the six ssh.* keys, tls.allowNegativeSerial, and mcp.forceLocalGateway. The other sixteen apply within the five seconds. Some of them, such as skills.defaultMode and sandbox.disk.dockerVolume, say in their description that only sandboxes created after the change see the new value.

Where the CLI and the docs disagree

The docs settings page and the CLI list different keys, and the settings table prints only the keys the CLI returned. Four keys are in the CLI and not in the docs: ssh.autoCreate, ssh.defaultAgent with default shell, ssh.defaultTemplate, and ssh.workspaceRoot, as conflict C20 records. Four keys are in the docs and not in the CLI output: feature.model, feature.sandbox-gpu, feature.udp-egress, and diagnostics.autoUploadErrorCooldownInDays, as conflict C19 records. The last one has a documented default of 1. The capture ran sbx settings get only on skills.defaultMode and kit.allowedSources, so what get answers for a feature.* key is open.

One default disagrees. The docs tell you to run sbx settings set platform.allowExperimentalFeatures true before feature.model, which implies false. The capture prints true with source default, as conflict C18 records.

{
  "default": true,
  "description": "Allow experimental features.",
  "env_var": "DOCKER_SANDBOXES_ALLOW_EXPERIMENTAL_FEATURES",
  "key": "platform.allowExperimentalFeatures",
  "source": "default",
  "type": "bool",
  "value": true
}

The same gap covers commands. The model.providers description names sbx run --model <model> --provider <id>, and the docs show sbx run --name <SANDBOX_NAME> --model <MODEL_NAME> --provider <PROVIDER_ID>, but sbx run --help in v0.47.0 lists neither flag. The secret help text mentions mounts that you add later with sbx mount, and the help tree has no sbx mount page. sbx ssh proxy, sbx policy approval, and --usb are named in the sources that conflict C16 lists, and none of them has a help page either. This manual documents what --help prints, and the command table is that list.

The kit defaults

Six kit.* keys decide which kits a sandbox accepts, and all six print default as their source. kit.allowedSources is ["docker.io/"], and kit.allowLocalKits and kit.allowExtractedAgents are true. kit.requireSignature and kit.ignoreTransparencyLog are false, and kit.trustedSigners trusts any @docker.com identity through https://accounts.google.com. Kit signing shows what a signature check does with them.

You started sbx run claude on a repository, and the agent is running docker build inside. On the host, docker ps shows nothing new, and you want to know where those images went and what else the agent can reach. sbx diagnose is the first command to run, because it names every layer between the agent and your machine.

When you finish this section, you can read sbx diagnose, name the five layers between the agent and the host, and name the doors through them.

What sbx diagnose checks

sbx diagnose: a read-only check of the installation, the platform, the storage, and the connection to the daemon, with --output json|github-issue and --upload. On the capture Mac it ran 13 checks, and all passed:

  Platform
  ✓ Virtualization — supported
      kern.hv_support is 1
  ✓ mkfs.erofs — found
      /opt/homebrew/Caskroom/sbx/0.47.0/Sbx.app/Contents/libexec/mkfs.erofs, default block size <n> bytes, guest kernel page size <n> bytes
…
  Connection
  ✓ Version match — v0.47.0
  ✓ Socket — responsive
  ✓ SSH client config — not configured
  ✓ Authentication — authenticated
…
  13 passed

kern.hv_support is 1 is the macOS flag for hardware virtualization. The guest runs on the host hypervisor: Hypervisor.framework on macOS, Windows Hypervisor Platform on Windows, and KVM on Linux (conflict C3). The mkfs.erofs line names the guest root filesystem format and its page size, which getconf PAGESIZE inside reports as 16384 (conflict C45). The last line is the sign-in check. sbx runs without Docker Desktop, and it still refuses to create a sandbox without a Docker account (conflict C15).

The FAQ gives two reasons: a sandbox belongs to a real person, and it authenticates against Docker infrastructure. It also lists the product's own egress hosts, starting with login.docker.com.

Five layers, from the kernel up

Inside m101-demo, the capture ran uname, id, docker version, and mount:

Linux m101-demo 7.0.14 #1 SMP PREEMPT Mon Sep 21 06:45:23 UTC 2026 aarch64 GNU/Linux
…
PRETTY_NAME="Ubuntu 26.04.1 LTS"
…
uid=1000(agent) gid=1000(agent) groups=1000(agent),27(sudo),1001(docker)
16384
…
Server: Docker Engine - Community
 Engine:
  Version:          29.8.1
…
 containerd:
  Version:          v2.3.5
…
bind-<id> on /etc/resolv.conf type virtiofs (ro,relatime)
host on $CAPTURE/fixtures/repo type virtiofs (rw,nosuid,nodev,relatime)

The docs name five isolation layers: hypervisor, network, Docker Engine, workspace, and credential. The listing shows four of them from inside. The guest kernel is 7.0.14 on aarch64 with 16 KiB pages, on Ubuntu 26.04.1. A build that assumes 4 KiB pages fails here, as one Docker Captain reported on 2026-05-26. The agent is user agent, uid 1000, in the sudo and docker groups, and the docs place the control elsewhere:

Docker Engine 29.8.1 and containerd v2.3.5 in the listing belong to the VM, and so does every image the agent builds. The docs state the consequence: the agent cannot reach the Docker daemon on your host.

The host side has no Docker API for the sandbox either. Kevin Wittek said on 2026-04-23 that the Moby API is not offered from the host. REST clients that expect it do not work against a sandbox, and sbx exec is the way in, as sbx exec, cp, and ports shows.

VMM: the virtual machine monitor that starts the guest. Docker wrote its own and said on Hacker News on 2026-08-10 that it is not Firecracker (conflict C4). The claim that it builds on libkrun stays unverified. The names the product exposes are few. sandboxd is the daemon, whose socket sbx daemon status prints. containerd runs inside the guest, EROFS appears in the diagnose line, virtiofs in the mount table, and nerdbox in the release assets.

The doors through the boundary

Kevin Wittek named four entry points into a sandbox on 2026-09-04: bind mounts, network, secret injection, and MCP. The capture shows each as one line in the guest. The workspace is host on $CAPTURE/fixtures/repo type virtiofs (rw,...), a mount at the same path as on the host. /etc/resolv.conf is a second, read-only virtiofs bind from the host, so the resolver is the host's. The network door is HTTPS_PROXY=http://gateway.docker.internal:3128 in the environment (the capture). The secret door is ANTHROPIC_API_KEY=proxy-managed, a sentinel.

The MCP door is MCP_GATEWAY_URL=http://mcp-gateway.docker.internal/mcp. A fifth line, SSH_AUTH_SOCK=/run/ssh-agent.sock with SSH_AUTH_SOCK_GATEWAY=gateway.docker.internal:3129, is the forwarded SSH agent, a door that the talk did not name. The docs turn that forwarding on by default, and secrets returns to it. Figure 3.1 stacks the layers and draws the doors.

The VM has limits of its own. --memory defaults to 50% of host memory, clamped to 512 MiB to 32 GiB. --cpus 0 means all host CPUs, at most 16 on Linux arm64. m101-policy got cpu 10 and memory 32 GiB on the capture Mac (the capture).

You let an agent work on a repository overnight. In the morning git diff is clean, and a new file sits in .git/hooks/pre-commit, where no diff ever shows it. The three workspace modes decide how much of your tree the agent can write. With --clone it can write none of it.

When you finish this section, you can pick a workspace mode for a repository and fetch an agent's commits out of a clone-mode sandbox.

Three workspace modes

Direct mount: the workspace path mounted inside the VM at the same absolute path, read-write. In m101-demo the agent's pwd is $CAPTURE/fixtures/repo, the same string as on the host. git log lists the host commits c7dfd56 second and 086df68 first (the capture).

The mount is virtiofs, as the microVM boundary showed, and the file synchronization of the legacy plugin is gone (conflict C5). Extra paths follow the first one, and :ro makes one read-only. A read-only argument can name a single file. That keeps one path out of reach in a workspace that the sandbox can otherwise write.

Mountless: no path on sbx create, so the VM has no host bind mount. The agent works in the template's working directory, /home/agent/workspace for Docker's templates. m101-policy was created that way, and sbx create printed workspace none · no workspace bind mount (the capture). sbx run without a path mounts the current directory instead, which sbx run, create, stop, and rm warns about.

Direct mode needs a review step. The docs list what the agent can edit, such as Git hooks, CI configuration, package.json scripts, and .claude/settings.json. They warn that hooks do not show up in git diff. A Docker Captain described this covert channel on 2026-05-26, and it is the reason clone mode exists.

Clone mode

--clone: a flag at creation that runs the agent on a private clone of the host Git repository inside the container. The host repository is mounted read-only. It replaced --branch in v0.31.0, and --branch now fails with --branch is no longer supported; use --clone instead (conflict C6). The flag is a no-op when you re-attach to an existing clone-mode sandbox. The capture created m101-clone with it:

$ sbx create --clone shell $CAPTURE/fixtures/repo-clone --name m101-clone
✓ Git repository detected: $CAPTURE/fixtures/repo-clone
…
  Git daemon: git://127.0.0.1:<port>/repo-clone
  Remote: sandbox-m101-clone
✓ Created sandbox m101-clone
  mount  $CAPTURE/fixtures/repo-clone → /run/sandbox/source (ro, source)
…
SANDBOX      AGENT   STATUS    PORTS                        WORKSPACE
m101-clone   shell   running   127.0.0.1:<port>->9418/tcp4   $CAPTURE/fixtures/repo-clone

Inside, three facts stand out (the capture). The clone sits at the same path, $CAPTURE/fixtures/repo-clone, on /dev/vde, an ext4 volume, and its origin is /run/sandbox/source. The source mount is host on /run/sandbox/source type virtiofs (ro,nosuid,nodev,relatime), and touch /run/sandbox/source/x fails with Read-only file system. A commit made inside, 81e11df from sandbox, cannot be pushed to origin either: git push ends with remote unpack failed: unable to create temporary object directory (the capture). The docs name the limit: clone mode keeps the agent from changing your host repository. Reading it is still possible, so an untracked .env under the repository is readable inside.

Getting commits back

The git-daemon in the VM listens on 9418, and sbx publishes it on a loopback port. The CLI then writes a remote into the host repository's .git/config:

$ git -C $CAPTURE/fixtures/repo-clone remote -v
sandbox-m101-clone	git://127.0.0.1:<port>/repo-clone (fetch)
sandbox-m101-clone	git://127.0.0.1:<port>/repo-clone (push)
…
file:.git/config	remote.sandbox-m101-clone.fetch=+refs/heads/*:refs/remotes/sandbox-m101-clone/*
file:.git/config	remote.sandbox-m101-clone.fetch=+refs/heads/*:refs/sandboxes/m101-clone/*
…
$ git -C $CAPTURE/fixtures/repo-clone fetch sandbox-m101-clone
…
   c7dfd56..81e11df  main       -> sandbox-m101-clone/main
   c7dfd56..81e11df  main       -> refs/sandboxes/m101-clone/main
…
81e11df from sandbox
c7dfd56 second
086df68 first

Two fetch refspecs mean one fetch updates two places: refs/remotes/sandbox-m101-clone/main and refs/sandboxes/m101-clone/main. sbx rm removes the remote and the daemon and prints the recovery command git branch <local-name> refs/sandboxes/m101-clone/<branch>. In the capture, refs/sandboxes/m101-clone/main survived the removal (the capture). sbx stop stops the daemon, and a restart assigns a new port and rewrites the remote URL. The /root/.config/git/attributes warning in the fetch output comes from the daemon's user inside the VM and changes nothing. sbx kit add keeps the clone on a named workspace volume, which is the ext4 device above, and sbx rm cleans up the Git worktrees.

Figure 3.2 follows one commit from the clone to the host refs.

Your agent reports that npm install failed with a connection error, and the sandbox keeps no shell history to say why. The question is which rule decided. sbx policy answers it in two halves: ls for the rules that exist, and check network for the decision one host would get.

When you finish this section, you can initialize a policy, add a rule in the right scope, and predict the decision for any host.

The preset and the global policy

policy init: sets the first global policy, not a default for each sandbox. It runs once, before the first sandbox, with allow-all, balanced, or deny-all, and sbx policy reset or sbx daemon start --policy starts over. The capture host chose balanced on v0.47.0, and sbx policy ls then showed one policy, local-policy, with network: 194 allow (the capture). The wide JSON lists eight rules with created_via: default: six network groups and two filesystem rules that allow every path. The list changes between releases without a changelog (conflict C23), so this is the list as recorded on 2026-10-08:

      "id": "default-ai-services",
      "name": "default-ai-services",
      "policy_id": "local-policy",
      "scope": "global",
      "applies_to": "all",
      "resource_type": "network",
      "decision": "allow",
      "resources": [
        "api.anthropic.com:443",
        "statsig.anthropic.com:443",
        "platform.claude.com:443",
…
        "**.openai.com:443",
…
      "id": "default-package-managers",
…
        "registry.npmjs.org:443",
…
        "pypi.org:443",
…
      "provenance": {
        "created_via": "default"
      },
      "actions": [
        "net:connect:tcp"
      ]

Rule grammar and scope

Allow rule: a comma-separated list of hostnames, domains, IP addresses, or CIDR prefixes. The forms are example.com, *.example.com, **.example.com, api?.example.com, api[12].example.com, example.com:443, [2001:db8::1]:443, a CIDR, and ** for every host. A lone * and an escaped glob are rejected. An allow rule covers TCP unless --protocol says otherwise, and a deny rule covers TCP and UDP. The capture shows both: the allow came back as (example.com [tcp]) and the deny as (example.com [tcp,udp]) (the captures). The deny also warned that UDP egress stays off until feature.udp-egress is on.

Two scopes have existed since v0.29.0 (conflict C41): global, the default, and local, which --sandbox scopes to one sandbox. A rule added with --sandbox m101-policy printed Rule added to policy local (scope: sandbox:m101-policy): <uuid>, and sbx policy inspect shows its scope, layer, origin, and provenance:

      "id": "<uuid>",
      "name": "<uuid>",
      "policy_id": "<uuid>",
      "scope": "sandbox:m101-policy",
      "applies_to": "sandbox:m101-policy",
      "resource_type": "network",
      "decision": "allow",
      "resources": [
        "example.com"
      ],
      "origin": "scoped",
      "layer": "local",
      "status": "active",
      "editable": true,
      "sandbox_id": "m101-policy",
      "provenance": {
        "created_via": "added"
      },
      "actions": [
        "net:connect:tcp"
      ]

--deny-network HOST on create or run adds the same kind of per-sandbox deny at creation. The help says why that is safe under governance: a local deny can only make egress narrower, never wider. A kit adds rules with created_via: provisioned, and sbx policy ls --source org on the capture host printed No policies match the selected filters. (the capture).

Deny wins: for the same hostname or CIDR, a deny rule wins over an allow rule. An allowed hostname is not checked against CIDR rules for the IP address it resolves to.

The CLI refuses a deny that conflicts with an allow in the same scope: deny: "example.com" conflicts with existing allow rule "<uuid>" (the capture). The capture removed the allow with sbx policy rm network --sandbox m101-policy --id <uuid> --force before the deny was accepted. Under organization governance only organization allow rules grant access, while local and kit deny rules still apply, and org policies prints that table.

policy ls filters with --source local|org|kit, --decision, --type, --created-via default|added|provisioned|approval, --protocol, --wide for RULE_ID, and --json. A wide row carries METHOD and PATH columns. The docs fill them with --method and --path flags. The v0.47.0 help of sbx policy allow network lists neither flag, so this manual marks local HTTP rules as unverified. The proxy returns to them.

check network

policy check network: a read-only call that runs the same policy authorizer in the daemon that enforces the sandbox network. A host without a port is evaluated with port 443, and the command checks network access only, not the HTTP method or path. It exits 1 on a denial. The capture ran it on example.com in the m101-policy context before any rule, after the allow, and after the deny:

{
  "action": "net:connect:tcp",
  "allowed": false,
  "context": "sandbox:m101-policy",
  "deny_kind": "explicit",
  "governance": {
    "active": false
  },
  "origin": "local",
  "reason": "Denied by local rule",
  "resource_type": "net:domain",
  "resource_value": "example.com:443",
  "rule": "local:<uuid>",
  "target": "example.com:443",
  "type": "network"
}

After the allow, the same call returned "allowed": true with no rule field (the capture). The global check of api.anthropic.com did the same under "context": "global" (the capture). The two denials differ in deny_kind: implicit names no rule, and explicit names local:<uuid>. An implicit denial is also what a sandbox turns into an approval request, which the next section shows. Figure 3.3 walks the request through the same order.

The agent says that https://example.com timed out. It did not time out: the proxy answered it in 90 bytes. Every connection from a sandbox passes a proxy on the host. sbx policy log keeps one row per host with the decision, the proxy path, and the rule.

When you finish this section, you can read a policy log row, name its proxy path, and tell a blocked host from a slow one.

Two proxies and one CA

Inside m101-demo, the environment carries the proxy address and its certificate:

HTTPS_PROXY=http://gateway.docker.internal:3128
HTTP_PROXY=http://gateway.docker.internal:3128
…
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
NODE_USE_ENV_PROXY=1
NO_PROXY=localhost,127.0.0.1,::1,gateway.docker.internal
…
PROXY_CA_CERT_B64=<base64>
…
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
…
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

The address is gateway.docker.internal:3128, not the host.docker.internal:3128 of the legacy plugin (conflict C26). The docs describe two paths. Agents send HTTP and HTTPS through a forward proxy, and other TCP traffic is forwarded transparently. Both paths enforce the network access policies.

The first prototype was only an environment variable, and an agent bypassed it with no_proxy, as Kevin Wittek said on 2026-01-14. The capture sent a request to gateway.docker.internal:18080, a name in NO_PROXY, so curl skipped the forward proxy and opened a plain TCP connection. The transparent path caught that connection, and the log recorded it as transparent and blocked (the capture).

TLS interception: the proxy's own certificate authority, carried as PROXY_CA_CERT_B64 and merged into /etc/ssl/certs/ca-certificates.crt. The capture shows where it is used:

$ sbx exec m101-policy sh -c 'curl -sS --max-time 10 -I https://example.com; echo exit=$?'
HTTP/1.1 200 OK

HTTP/1.1 403 Forbidden
Content-Length: 90
Content-Type: text/plain

exit=0
[exit 0]

$ sbx exec m101-policy sh -c 'curl -sS --max-time 10 https://example.com; echo; echo exit=$?'
Approval required for example.com:443.

Review and respond with:
  sbx policy approval ls

exit=0
[exit 0]

HTTP/1.1 200 OK is the proxy accepting the CONNECT. The 403 Forbidden that follows arrived inside the TLS session, under a certificate the sandbox trusts, and its 90-byte body is the approval message. After sbx policy allow network --sandbox m101-policy example.com, the same request got HTTP/1.0 200 Connection established and then HTTP/2 200 with server: cloudflare (the capture).

The log classed that one as forward-bypass, a tunnel without inspection and without credential injection. So the ruling for C26 reads: the proxy terminates TLS only when it has to speak. That is a blocked host or a host with a bound credential, and it tunnels the rest. The v0.47.0 notes name both paths: a CONNECT tunnel without interception, and a late handshake check in the transparent proxy.

Reading policy log

policy log: shows which hosts the proxy allowed or blocked, with the matching rule, the proxy type, and the request count. It takes [SANDBOX], --json, --limit, and --type, and the help admits that filesystem logs are not supported yet (conflict C28). The JSON has two arrays:

{
  "blocked_hosts": [
    {
      "host": "example.com:443",
      "vm_name": "m101-policy",
      "proxy_type": "forward",
      "rule": "denied: rule \"local:<uuid>\" matched op(action=net:connect:tcp, resource=net:domain:example.com:443)",
      "last_seen": "<ts>",
      "since": "<ts>",
      "count_since": "<n>",
      "reason": "Denied by local rule"
    },
…
  "allowed_hosts": [
…
    {
      "host": "example.com:443",
      "vm_name": "m101-policy",
      "proxy_type": "forward-bypass",
      "rule": "",
      "last_seen": "<ts>",
      "since": "<ts>",
      "count_since": "<n>"
    },

Each row has host, vm_name, proxy_type, rule, reason, last_seen, since, and count_since. A blocked row names the operation, op(action=net:connect:tcp, resource=net:domain:example.com:443), and either no applicable policies or the rule that matched. An allowed row in this capture carries an empty rule, so the log says that a host passed, and check network says why. PROXY takes five values, forward, forward-bypass, transparent, network, and browser-open. Figure 3.4 animates both requests.

The 403 body names sbx policy approval ls. The docs describe approval ls, inspect, and respond. Under balanced and deny-all, a request that matches no rule waits for your approval instead of being denied at once. The v0.47.0 help tree has no sbx policy approval command, while sbx policy ls --created-via approval exists (conflict C16).

What a host rule cannot see

A deny covers more than TCP (conflict C27). A 2026-05-26 post said UDP and ICMP are blocked and cannot be allowed. Since v0.33.0 a sandboxed process cannot resolve a domain that policy denies, loopback names excepted, and outgoing ICMP stays blocked. Since v0.45.0 UDP follows policy behind the experimental setting feature.udp-egress, and DNS resolution stops when no rule permits it. The ruling: a deny covers TCP, UDP, and the name lookup itself, and ICMP cannot be allowed. The guest's /etc/resolv.conf is a read-only bind from the host.

A host allow permits every request to that host, with any method, path, and body. The balanced preset allows github.com:443 and **.github.com:443 (the capture). Docker staff said on 2026-04-07 and on 2026-08-10 that an issue body or a gist on an allowed host is not blocked.

The product's answer is the HTTP rule. A kit's network-policy@2 entry can deny hosts: [api.github.com] with methods: [DELETE]. A network allow is a ceiling that HTTP rules carve into, and neither check network nor policy log evaluates a method or a path. Figure 3.5 puts the two rules side by side.

Upstream proxies are a separate setting: proxy, proxy.sandbox, proxy.daemon, and the no_proxy family, with SOCKS5 since v0.35.0. The settings table lists the keys.

You exported ANTHROPIC_API_KEY in ~/.zshrc, as a 2026 tutorial said, and the agent inside the sandbox still has no key. Since v0.35.0 the host environment is not read (conflict C7). -e KEY passes a plain variable, not a secret, and the three sbx secret commands are the only way in.

When you finish this section, you can store a service secret, bind a custom one to a host, and read what the proxy sent.

Service secrets

Service secret: a value stored under one of 13 service names, anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai, two more than the docs table (conflict C21). The value comes from -t, from stdin, from --command, or from --ref with a 1Password op:// reference or an AWS Secrets Manager ARN. --oauth is the fifth source, and locally it works only for openai at global scope (conflict C22). Anthropic OAuth comes from the agent's own login instead. Since v0.46.0, a command helper runs from a new temporary directory on the host, so a relative helper path no longer resolves (conflict C38). --refresh sets the cache time, default 55 minutes.

The scope is global unless --sandbox narrows it. secret ls filters with -g, --sandbox, --service, and --json, and secret rm takes --all, --placeholder, and --registry. The store is the macOS Keychain, the Windows Credential Manager, or the Linux Secret Service. Without a keyring, Linux uses a file under ~/.config/com.docker.sandboxes at mode 0700. Kit approvals live apart from the values, in ~/.config/sbx/credentials.yaml.

secret import: reads the host environment once, offers each variable with a last-4 preview, and takes --all, --force, and --dry-run. A service that already holds an OAuth token is skipped. On the capture host nothing was exported:

$ sbx secret import --dry-run
No credential env vars detected on the host. Set e.g. OPENAI_API_KEY in your shell and re-run, or use `sbx secret set` to enter a value directly.

Registry credentials are a third kind, "host-only by default", and reach a sandbox only with --all-sandboxes or --sandbox.

What the agent sees

Every service variable inside a sandbox is a sentinel, and the GitHub one is shaped like a token:

ANTHROPIC_API_KEY=proxy-managed
…
GH_TOKEN=gho_sbxproxymanaged000000000000000000000
…
OPENAI_API_KEY=proxy-managed
…
SBX_CRED_ANTHROPIC_MODE=none
SBX_CRED_GITHUB_MODE=none

Three formats exist in v0.47.0 (conflict C35): proxy-managed for the eight provider keys, gho_sbxproxymanaged000000000000000000000 for GH_TOKEN, and sbx-cs-<rand> for custom secrets. The GitHub one is lower case, where a 2026-09-04 demo showed GHO_SBX_PROXY_MANAGED. No GitHub request was captured: that needs a real token.

Custom secrets and the receiver

set-custom: an experimental secret keyed to --host targets and an --env name instead of a service. The value comes from --value, --command, or --ref, and --placeholder sk-{rand} sets a chosen prefix. The --header and --format flags apply with --cloud only, as the help states for each (conflict C34). The capture bound M101_RECV_KEY to host.docker.internal and localhost, and started a receiver on the host at 127.0.0.1:18080. It allowed localhost:18080 for m101-secret and found M101_RECV_KEY=sbx-cs-<rand> inside (the capture). Then it sent three plain HTTP requests:

GET /from-variable HTTP/1.1
Host: localhost:18080
User-Agent: curl/8.18.0
Accept: */*
Authorization: Bearer m101-dummy-receiver-0000
X-Demo: m101-dummy-receiver-0000
Accept-Encoding: gzip
…
GET /no-scheme HTTP/1.1
Host: localhost:18080
…
Authorization: m101-dummy-receiver-0000

The receiver saw the real value in every place the placeholder appeared: inside Bearer, in X-Demo, and as the whole Authorization value. Its Host was localhost:18080: the proxy maps host.docker.internal to localhost. So the swap happens on plain HTTP, and it is a substring replacement. That settles conflict C34 for custom secrets. The Hacker News claim that the secret must be the whole header describes service secrets, where the kit declares the header and its format.

The fourth request went to gateway.docker.internal:18080, a name in NO_PROXY, so it bypassed the forward proxy. The transparent proxy blocked it with Empty reply from server and swapped nothing (the capture). Figure 3.6 animates the four steps. The existing sandbox m101-demo did not receive M101_RECV_KEY (the capture), so a custom variable reaches new sandboxes only. Removal is immediate: sbx secret rm --placeholder sbx-cs-<rand> -f printed Applied secret updates for <n> running sandbox(es) (the capture).

The SSH agent

One credential path does cross the boundary. SSH agent forwarding is on by default, and the guest shows SSH_AUTH_SOCK=/run/ssh-agent.sock with SSH_AUTH_SOCK_GATEWAY=gateway.docker.internal:3129 (the capture). Keys stay on the host, and any process inside can ask that agent to sign. ssh.agentForwardingEnabled in sbx settings list turns it off, followed by sbx daemon restart. MCP secrets stay on the host too, under mcp:<server>:client_secret, as sbx mcp add explains.

You want the agent to read documentation through an MCP server, and you do not want that server's token inside the VM. sbx mcp keeps the registration, the OAuth tokens, and any local server process on the host, and gives the sandbox one URL.

When you finish this section, you can register a server, pick static or dynamic mode, and load a server into a running sandbox.

Register on the host

sbx mcp add: registers an MCP server by name. sbx validates the server and stores its specification for --static-mcp on sbx create and sbx run.

--url takes four forms: a remote endpoint, a community-registry URL, a server.json or server.yaml manifest URL, and a dhi.io/ image reference. Other image references are rejected, and --local runs a registry OCI server on the host with docker run. The capture registered one remote server and listed it:

{
  "gateway": {
    "name": "LOCAL",
    "local": true,
    "operator": "managed by you",
    "decision": "local",
    "signed_in_as": "<docker-user>"
  },
  "servers": [
    {
      "name": "m101-deepwiki",
      "transport": "remote http",
      "status": "ready",
      "type": "remote"
    }
  ]
}

The help's own registry example did not resolve on 2026-10-08: the add of https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest failed with registry returned status 404 (the capture). --command is the other input, and it runs on the host with all the permissions of your host user. A local server that starts a container uses host Docker, outside the engine boundary of the microVM.

OAuth metadata is discovered through RFC 9728 and RFC 8414, or supplied by hand with --oauth-authorization-server. --client-id names a pre-registered client, and dynamic registration follows RFC 7591. --scope records default scopes with a documented precedence, --resource sets the RFC 8707 indicator, and --callback-port pins the listener. Tokens stay on the host, and sbx mcp auth [server|--all], auth status, and auth rm manage them.

The deepwiki server needs none: sbx mcp inspect reports requires_oauth: false, and auth status --all --json printed [], so no OAuth flow was captured. A confidential client's secret and any --header 'Name: ${placeholder}' value come from the secret store as mcp:<server>:client_secret and mcp:<server>:<placeholder>. A header-bearing registration is rejected on the hosted gateway.

One gateway per sandbox

MCP gateway: an endpoint on the host that gives agents access to the registered MCP servers. Inside m101-mcp the environment holds MCP_GATEWAY_URL=http://mcp-gateway.docker.internal/mcp and MCP_SENTINEL_TOKEN_NAME=proxy-managed (the capture). The docs list the agents that read that URL at start: Claude Code, Codex, Devin, Gemini, Kiro, and OpenCode. Docker Agent is absent from that list. A plain shell sandbox reached the gateway with curl all the same (the capture):

HTTP/1.1 200 OK
…
Content-Type: text/event-stream
…
Mcp-Session-Id: <session>
…
event: message
id: <event-id>
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true},"tools":{"listChanged":true}},"instructions":"### m101-deepwiki…"protocolVersion":"2025-11-25","serverInfo":{"name":"mcp-gateway-m101-mcp","version":"0.1.0"}}}

The gateway names itself mcp-gateway-m101-mcp, one per sandbox, answers protocol version 2025-11-25, and declares tools.listChanged: true. sbx mcp ls adds a GATEWAY column, LOCAL, managed by you, with signed_in_as in the JSON. mcp.forceLocalGateway, default false, and SBX_MCP_URL=none select the local data plane when an account would otherwise use the hosted gateway.

The docs separate it from the Desktop product: sbx mcp works without the Docker Desktop MCP Toolkit. Network policy does not apply to a server the host registered, as Kevin Wittek said on 2026-09-04. A server the agent starts inside the VM is subject to it. DMR, Compose models, and the MCP gateway service covers the Toolkit gateway.

Static and dynamic

Static mode: --static-mcp a,b at create or run fixes the set once at creation. The static sandbox exposed the three deepwiki tools plus code-mode and mcp-exec, and no discovery tool. The dynamic sandbox started with discovery tools only, and sbx mcp load m101-deepwiki --sandbox m101-mcp-dyn added the three:

$ sbx mcp load m101-deepwiki --sandbox m101-mcp-dyn
MCP server "m101-deepwiki" loaded into sandbox "m101-mcp-dyn" (live)

The help promises the notice: connected agents see the tools of the new server at once, through the standard MCP tools/list_changed notification. The probe opened a new session for each run, so it recorded the two lists and not the notification itself. The built-in tools belong to the gateway: mcp-exec, code-mode, mcp-find, mcp-add, mcp-config-set, and <server>-authorize for OAuth servers. In Cedar MCP policies those are MCP::Primordial resources and a server's tools are MCP::Tool resources, which org policies returns to.

sbx mcp catalog was removed in v0.45.0, and the sbx mcp enable of the product page never existed (conflict C11). Figure 3.7 draws the store, the two gateways, and the load. For the protocol itself, read the MCP lesson.

Your team wants every Codex sandbox to carry the same three tools, the same two allowed hosts, and the same instructions. A kit declares the tools, the hosts, and the credentials in one file, and the file travels as an image.

When you finish this section, you can read a v3 descriptor line by line and say what the frontend writes into the image. You can also tell which commands build, inspect, and run it.

One image, one annotation

Kit: one OCI image whose manifest annotation vnd.docker.sandbox.kit.descriptor carries the kit's declarations, while its layers carry the content. Stock tooling can pull a kit, inspect it, and use it in FROM. An engine that does not read the annotation runs it as an ordinary image.

Workload: a kit whose layers are a root filesystem and whose image config carries the launch command. A composition has exactly one.

Mixin: a kit whose layers are an overlay applied on a workload's filesystem, zero or more per composition. A third kind, set, exists only while you write the kit. Publishing turns it into workload or mixin from the kits that it lists.

The descriptor, line by line

The capture kit wrote one v3 descriptor, a shell workload with an inline recipe and a single network grant:

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: workload
displayName: hello-kit
description: A shell workload with one network grant, in the v3 descriptor form.
version: "1.0.0"
licenses: [Apache-2.0]
build: |
  FROM docker/sandbox-templates:shell
  COPY HELLO.md /home/agent/HELLO.md
capabilities:
  - type: com.docker.sandbox/network-policy@2
    config:
      runtime:
        allow:
          - example.com

The first line of the descriptor, # syntax=docker/sandbox-kit:3, selects the frontend. schemaVersion must be exactly the string "3", and kind is workload, mixin, or set. displayName, description, version, and licenses are optional display metadata. No name field exists, because identity is the reference that a kit is consumed by.

The build: field holds plain Dockerfile text. capabilities is a list of entries with type and config. Here one network-policy@2 entry allows example.com in the runtime phase, the agent's steady state.

Decoding is strict: a field that the parser does not know is an error anywhere in the document. The reason is policy. A misspelled key that the parser ignored would be a policy that is missing without a warning. Figure 4.1 puts the file beside the manifest that the build pushed.

What the frontend publishes

docker buildx build ./my-kit -f ./my-kit/my-kit.yaml -t docker.io/<NAMESPACE>/my-kit:1.0.0 --push builds and publishes a kit. The capture kit ran it against a local registry with a docker-container builder (28-builder.txt, 28-buildx.txt), and the registry returned this manifest:

  "mediaType": "application/vnd.oci.image.manifest.v1+json",
…
  "annotations": {
    "org.opencontainers.image.description": "A shell workload with one network grant, in the v3 descriptor form.",
    "org.opencontainers.image.licenses": "Apache-2.0",
    "org.opencontainers.image.title": "hello-kit",
    "org.opencontainers.image.version": "1.0.0",
    "vnd.docker.sandbox.kit.built-by": "{\"name\":\"docker/sandbox-kit\",\"version\":\"3.0.0-m.8\",\"revision\":\"129be2ff45e8f9463450eb3cf04ddcb52c2b76e5\"}",
    "vnd.docker.sandbox.kit.capabilities": "com.docker.sandbox/network-policy@2",
    "vnd.docker.sandbox.kit.descriptor": {
      "schemaVersion": "3",
…
      "provides": [
        "deb/adduser@3.153",
…
        "... 397 more derived provides entries"
      ],
…
    "vnd.docker.sandbox.kit.schema-version": "3"

The descriptor annotation holds the published descriptor as compact JSON, with the build: text kept. For a workload, the frontend also reads the package database and adds one deb/ entry per installed package. schema-version and capabilities repeat two fields, and the org.opencontainers.image.* keys copy the display fields. The build staged the sources at /usr/share/sandbox/kit/kit, after the stem of kit.yaml.

Which commands accept a v3 kit

Conflict C13 asks which generation each command accepts, and the captures settle it:

$ sbx kit validate ./fixtures/kits/hello-kit
error: kit ./fixtures/kits/hello-kit is a v3 source kit and this load path has no kit builder configured; artifact validation failed
[exit 1]

$ sbx kit inspect ./fixtures/kits/hello-kit --json
   → build kit ./fixtures/kits/hello-kit (sbx-kit-src:kit-<id>)
error: build kit ./fixtures/kits/hello-kit: exit status 1 ERROR: failed to build: OCI exporter is not supported for the docker driver. Switch to a different driver, or turn on the containerd image store, and try again. …
[exit 1]

The ruling: sbx kit validate, pack, push, and pull are v1 and v2 tooling. pack refused the directory too, for lack of a spec.yaml (13-kit-v3-pack.txt). The documentation agrees: use Buildx for v3 kits, because sbx kit pack, push, and pull are for v1 and v2 kits.

A v3 kit is consumed by sbx run and --kit, since sbx run and sbx create accept a kit reference in the place of the agent name. The pushed hello-kit still never reached a sandbox, because kit.allowedSources defaults to ["docker.io/"] (C40, 02-settings.txt):

$ sbx create localhost:15000/m101/hello-kit:v1 fixtures/repo-kit --name m101-v3
error: resolve kits: kit "localhost:15000/m101/hello-kit:v1": kit "localhost:15000/m101/hello-kit:v1" cannot be installed — its source is not in your allowlist; current kit.allowedSources: docker.io/; …
  try: sbx settings set kit.allowedSources '["docker.io/","localhost:15000/m101/"]'
…
[exit 1]

The capture kit never changes sbx settings, so no capture shows sbx running a v3 kit. Two rules limit the mix. A sandbox cannot combine v3 kits with v1 or v2 kits. The built-in agent names, such as claude and codex, select v2 kits. Docker publishes its v3 workloads as docker/sbx-kit-*, such as docker.io/docker/sbx-kit-codex:0.155.1.

Where the run and the pages disagree

Five results of the run contradict the specification or the documentation, and rows C113 to C117 of the register cover them. The table prints both sides:

An image without the descriptor annotation is not a kit to any consumer, so build with a docker-container builder. A consumer that finds no annotation on the index reads the platform manifest. The specification calls itself experimental, with a final version targeted for Q4 2026.

The default size of a kit volume stays in dispute (C12). The v0.39.0 notes say 512 MB, the research notes say 20 GiB, and this manual prints both. kit-tck validate judges a published artifact, kit-tck inspect reads it back, and this manual ran neither. Section 7.4 lists the claims it checked instead.

The gh mixin a colleague published reaches api.github.com with your token. You want to know exactly which requests it can make with that token, and what changes when version 2 arrives. Both answers are in its capabilities list.

When you finish this section, you can read that list, predict the merged grant set, and say which update will stop and ask.

Typed, versioned requests

Capability: one typed request in the capabilities list of a kit, for something that the kit needs and cannot supply itself. The host answers each one: granted, refused, or prompted.

Each entry has a type of the form <namespace>/<name>@<version>, an optional display name, and an optional flag. Its config is decoded strictly for the types the specification defines, so an unknown key is an error. The version names the config schema, so network-policy@1 and @2 both exist and a descriptor states one of them. A type that describes a policy appears once, while instance-shaped types repeat once per thing requested, such as credential@1 per service and phase.

Unknown types are allowed by design, because new types are how the format grows. A required unknown type fails resolution, and an optional one is skipped and recorded.

The nineteen types at the pin

The table is kitspec §7.2 at the v3.0.0-m.8 tag. The main branch adds a twentieth, com.docker.sandbox/agent-interactive-sessions@1, as a singleton, unreleased at the pin. The newest type in sbx itself arrived with the pinned release. A kit can declare com.docker.sandbox/long-running@1 to keep a local sandbox running after all its sessions disconnect.

network-policy@2 and credential@1

A network-policy@2 entry is a plain host string or an object with hosts, methods, and paths. A host string grants the connection for any protocol, as @1 did. An entry with methods or paths is bounded: it grants those HTTP requests and nothing else on that host. Deny entries list what to refuse, and a deny wins. A refused request gets a status, because a runtime must answer it with HTTP status 403. The proxy that enforces this is the one in the policy log section.

A credential@1 entry names a service and a phase, and never the place where the secret is kept. With apiKey.proxyManaged, the real value stays on the host. Every inject domain must appear in the allow list of the same phase. The binding that answers it is the one the secret section stores.

Resolution and the merged set

A runtime must include exactly one workload kit in each composition. It must fail when two kits provide the same normalized name, so claude plus claude-mixin is refused. Across the set, allow entries union per phase, deny entries union per phase, and deny wins on the result. When one kit allows a host outright, another kit's bounded entry for that host is dropped, because the union is the unbounded grant. Figure 4.2 runs that arithmetic on three kits.

What a grant looks like inside sbx

The recording host ran a v2 mixin, so the captured rows come from permissions.network.allow rather than a v3 entry. The daemon stores the grant as a policy rule the sandbox owner cannot edit:

      "name": "kit:m101-kit",
…
      "scope": "sandbox:m101-kit",
…
      "resource_type": "network",
      "decision": "allow",
      "resources": [
        "example.com"
      ],
…
      "editable": false,
…
        "created_via": "provisioned",

sbx policy check network example.com --sandbox m101-kit --json then answers "allowed": true (the capture). The rule carries created_via: provisioned and answers to --source kit, which is how the policy section tells a kit rule from one you added.

Updates and the lock

Every grant maps onto one normalized set. A consumer that controls updates stores that set in its lock file and compares each candidate against it. A new version whose set stays inside the stored one can apply silently. Any widening must stop for approval.

The list is explicit. It holds a new allow entry, a removed deny entry, and a new credential, path, or port. Write access over a read-only skills path is also on it. A removed deny counts, because the deny was part of what made the grant acceptable. optional does not change the set. Six types contribute nothing to it: resources@1, lifecycle@1, agent-context@1, agent-sessions@1, sbx@1, and long-running@1.

You wrote a v2 mixin that installs tree and drops a HELLO.md into the workspace. A colleague wants it without cloning your repository, and your security team wants to know who signed it. The sbx kit commands cover both, as long as the kit is v1 or v2.

When you finish this section, you can validate and pack a v2 kit, and describe what push --sign attaches to the manifest. You can also verify a signature and add a mixin to a running sandbox.

spec.yaml and files/

Mixin (v2): a directory with a spec.yaml whose schemaVersion is "2" and kind is mixin, plus an optional files/ tree. The capture kit wrote one:

schemaVersion: "2"
kind: mixin
name: hello-mixin
description: Installs tree and adds a greeting file to the workspace.
setup:
  install:
    - command: apt-get update && apt-get install -y tree
      user: "0"
      description: Install tree
permissions:
  network:
    allow:
      - example.com

files/workspace/HELLO.md holds one line, and sbx kit inspect reports it as a workspace file with mode 420 (the capture). The v2 grammar is the one the built-in agents use, and its normative text lives in SPEC-v2.md of docker/sbx-kits-contrib.

validate and pack

sbx kit validate REFERENCE accepts a directory, a ZIP, or a git reference, and --json reports a verdict and warnings:

{
  "reference": "./fixtures/kits/hello-mixin",
  "kind": "directory",
  "valid": true,
  "warnings": []
}

$ sbx kit pack ./fixtures/kits/hello-mixin -o $CAPTURE/work/hello-mixin.zip
Packed artifact to $CAPTURE/work/hello-mixin.zip
[exit 0]

$ zip listing of work/hello-mixin.zip (size, name)
       0  files/
       0  files/workspace/
      22  files/workspace/HELLO.md
     297  spec.yaml

For pack, the directory must hold a valid spec.yaml and can hold a files/ directory. The same ZIP validates with kind: "zip" (the capture). A v3 directory fails both commands, as the descriptor section showed. Figure 4.3 draws the whole path, with the steps the capture kit did not run in dashed boxes.

sign, push --sign, and pull

The capture kit ran none of these three, because it has no registry and no signing identity. The help text is the source. sbx kit sign is keyless by default, with an OIDC token from the CI provider or a browser login. It never reads a token from SIGSTORE_ID_TOKEN, so a process that can set an environment variable cannot choose the token. With --key it signs with an unencrypted PEM private key. For a local directory, it writes a detached signature bundle to kit.sig.bundle next to spec.yaml.

sbx kit push DIRECTORY REFERENCE chooses the artifact form from schemaVersion: a ZIP for "1", a tar+gzip layer with the spec in the config blob for "2". With --sign, the push signs the manifest and attaches the Sigstore bundle to the kit as an OCI referrer. Every push also attaches a SLSA provenance attestation as an OCI referrer, and that provenance is signed only with --sign. --tlog-upload=false keeps a private kit out of the Rekor log. For pull, the registry must support HTTPS.

The same command signs a published v3 image by reference. A v3 kit that you share as a source directory or a Git reference cannot be signed.

verify, provenance, and the settings that admit a kit

sbx kit verify takes --key PUB for a key, or --certificate-identity with --certificate-oidc-issuer for a keyless signature. --insecure-ignore-tlog accepts a private keyless signature, and the flag changes nothing for a key-based verification. sbx kit provenance REFERENCE prints the attestation, and it reports an attestation as VERIFIED only when it verifies and its subject matches the digest of the kit.

Six settings decide what a sandbox accepts, all at their defaults on the recording host:

kit.allowExtractedAgents             true                               bool     default             Admit the pinned kit references that replace fo…
kit.allowLocalKits                   true                               bool     default             Allow installing kits from local directories or…
kit.allowedSources                   ["docker.io/"]                     json     default             JSON array of allowed kit source prefixes (e.g.…
kit.ignoreTransparencyLog            false                              bool     default             Verify keyless kit signatures without requiring…
kit.requireSignature                 false                              bool     default             Require a valid signature from a trusted signer…
kit.trustedSigners                   [{"identityRegexp":"^.*@docker\…   json     default             JSON array of trusted signer policies (key-base…

When kit.requireSignature is true, sbx rejects unsigned kits, signatures that do not match kit.trustedSigners, and ZIP kits. The default kit.trustedSigners policy trusts Docker employee identities that end in @docker.com, attested by the Google issuer. The settings table lists the environment variable of each key.

kit add and the builder

sbx kit add SANDBOX REFERENCE recreates the container with the mixin added, and it keeps the volumes that kits own, such as agent session state, across the swap. The capture shows the accepted case and the refused one:

$ sbx kit add m101-demo ./fixtures/kits/env-mixin
Recreating sandbox "m101-demo" to apply augmented kit list...
  Swap container m101-demo-swap-<id> started (id=<sha256>).
Kit "env-mixin" added to sandbox "m101-demo"
[exit 0]

$ sbx exec m101-demo sh -c 'env | grep M101_FROM_KIT'
M101_FROM_KIT=yes
[exit 0]

$ sbx kit add m101-demo ./fixtures/kits/hello-mixin
error: kit "hello-mixin" declares files, which the kit-add recreate flow does not yet apply; recreate the sandbox from scratch via `sbx rm` + `sbx create --kit` to use this kit
[exit 1]

Sandboxes created before the recreate-aware label are refused with an error, and long-running@1 cannot be added this way. sbx create shell --kit ./fixtures/kits/hello-mixin applied the same mixin in full: one install command, one workspace file, and one allow rule (the captures).

Source-form builds of v3 kits run in a shared builder sandbox named sbx-kit-builder, which sbx creates on first use. sbx kit builder status reports it, and history passes through to docker buildx history:

$ sbx kit builder status
Builder:      not created (the first source-form kit build creates it)
Builder kit:  docker.io/docker/sbx-kit-builder:1
Kit registry: 127.0.0.1:5411 — reachable
[exit 0]

A new contributor clones your repository and needs the sandbox you use. That means the shell workload, the hello-mixin, one published port, a greeting variable, and a host command that prepares the workspace. You could send a list of flags. An environment file sends the same thing as one checked-in file, and the contributor sees a plan before anything runs.

When you finish this section, you can write an sbxenv.yaml, read its plan symbol by symbol, and say which edits wait for the next create.

The file

Environment file: a sbxenv.yaml that declares one sandbox and the host resources around it, read by the five sbx env commands. The capture kit wrote this one:

schemaVersion: "1"
name: m101-env
agent: shell
workspace: .
args:
  greeting:
    default: hello
    description: Greeting word
kits:
  - source: ../kits/hello-mixin
env:
  GREETING: ${{ env.args.greeting }}
lifecycle:
  initialize:
    - command: echo init
ports:
  - sandbox: 8080
    host: 18083

The keys come from the file reference and from the command's own help. Three placeholders expand, ${{ env.args.NAME }}, ${{ env.projectDir }}, and ${{ env.fileDir }}, and a $ anywhere else is literal text. A relative kit path or workspace resolves against the directory of the file that declares it, so workspace: . mounts the file's own directory. A file with no workspace mounts nothing.

The plan

sbx env plan reads the file and prints what applying it would set up. It applies, approves, and records nothing.

── ENVIRONMENT PLAN
   m101-env

   kits:
+    - source: $CAPTURE/fixtures/kits/hello-mixin

   workspace:  (present, not recorded as applied, needs your approval)
     path: $CAPTURE/fixtures/env

   env:
+    GREETING: hello

+  sandbox:
+    name: m101-env
+    agent: shell

   ports:
+    - sandbox: 8080
+      protocol: tcp4
+      host: 18083

   lifecycle:
     initialize:
+      - command: echo init
+        workdir: $CAPTURE/fixtures/env
+        envFiles:
+          - $CAPTURE/fixtures/env/sbxenv.yaml

   Plan: + 5 to add, ~ 0 to change, - 0 to destroy.

   this plan runs commands on this machine, outside the sandbox, with your own privileges
   ✓ not approved yet; applying asks once

The plan has the shape of your file, and the margin carries the verdict. Five symbols exist. + adds, ~ changes, and - destroys. > marks a command that runs again, and ! marks a resource the environment applied and no longer declares.

A row that is unchanged and already approved is left out. A literal secret value appears as its SHA-256 digest. The tcp4 protocol was not in the file: published ports default to it since v0.42.0. Figure 4.4 follows the file through the plan to the state record.

Host commands and approval

The lifecycle block runs on the host, outside the sandbox, with your own privileges. initialize runs on every create and every run, postCreate once the sandbox exists, and preRemove after you confirm sbx env rm. Commands run through your shell from the project directory, with workdir and timeout per command. An environment with any of them asks on every invocation, even one that does not run them. The reason is that approving a command also trusts the script it calls. --skip-host-commands runs none of them, --auto-approve answers yes once, and sbx settings set env.rememberHostCommands true asks again only when a command changes.

The state record and the second plan

sbx records what you approved for each environment in its state directory, not next to the file. A later invocation asks only about what changed. The exact path was not captured, because the kit ran plan and never create. The second capture changed one input instead:

$ sbx env plan --env-arg greeting=servus ./fixtures/env
…
+    GREETING: servus
…
   Plan: + 5 to add, ~ 0 to change, - 0 to destroy.

Every row is still +, because nothing was applied. After a create, the same edit prints ~ GREETING: hello -> servus and nothing else, in the form the help text shows for a changed kit argument. Changes to workspaces, kits, ports, secrets, bindings, and sandboxOptions wait for the next create. New env values reach the next session.

Several PATH arguments deep-merge in order, and a later file wins over an earlier one, and lists such as ports concatenate rather than override. With no PATH, a .sbxenv.yaml in your home directory merges underneath as a base layer. A hidden .sbxenv.yaml in the project is no longer read.

rm, the read-only file, and --cloud

sbx env rm removes the sandbox and the secrets provisioned at its scope. Bindings stay, because they belong to the user. To remove the bindings that this environment declares too, pass --prune-bindings. The file itself is bound read-only inside the sandbox, because an agent that can edit it decides what the next plan asks about. sandboxOptions.writableEnvFiles: true lifts that.

With --cloud, workspace, additionalWorkspaces, and clone are refused, because they name host directories that a cloud sandbox cannot mount. Also, host port bindings, MCP definitions, and dynamic secret sources are rejected before any host command runs. The cloud section shows what remains.

You keep a pdf skill under ~/.claude/skills on your laptop. Inside a sandbox the agent has its own home directory and never sees it. The shared skills store is the one place you fill, and every sandbox for a supported agent reads it.

When you finish this section, you can fill the store, choose how each sandbox mounts it, and turn the same skills on for docker-agent.

The store

Skill: a directory with a SKILL.md whose metadata an agent reads into its system prompt, and whose body it loads when a task matches.

Shared skills store: the host directory that sbx links into every sandbox for a supported agent. On the recording host it was empty:

{
  "store": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills",
  "skills": []
}

On Linux the store is ~/.local/state/sandboxes/sandboxes/agent-skills, and on Windows %LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills. sbx reset clears the shared store.

add, import, ls, rm, and update

sbx skills add <repository> installs from a Git URL or a GitHub owner/repository, and the repository must hold at least one valid SKILL.md file. --skill NAME picks skills by name, repeatable or comma-separated, so sbx skills add anthropics/skills --skill pdf installs one. The capture kit did not record an add, because the step needs GitHub. sbx skills update refreshes only skills that add installed, and sbx skills rm asks before it removes one.

sbx skills import copies skills already installed on the host, checking six directories in order, and the first copy of a duplicate name wins:

The order comes from the help text and the mount targets from the docs. Claude, Codex, Copilot, Cursor, Droid, and OpenCode can use the imported skills. sbx skills import arrived in v0.37.0, and add, update, and rm in v0.42.0.

How a sandbox sees the store

By default, the entries of the store are linked read-only into the skills directory of the agent. The directory itself stays writable, so kits can install skills beside them. The links are made when the container starts. So an edit to an existing skill is live, while a new store entry reaches a running sandbox only on its next start. Removing a skill breaks its link at once.

--skills off|readonly|readwrite on sbx run or sbx create chooses the mode per sandbox, and readwrite mounts the store over the directory so the sandbox's writes are shared. The default is readonly, or the skills.defaultMode setting, which the recording host had at its default (the capture). The three-way flag replaced --no-share-skills in v0.43.0. The capture kit did not list that directory from inside a sandbox, so the link form is not shown.

In a v3 kit the agent declares the path itself, with agent-skills@1, because a runtime cannot know where any agent reads its skills. When mode is left out, a runtime must use readonly. The effective access is the narrower of the host setting and the kit's mode. Raising a path to readwrite is a widening that stops for approval, as the capabilities section explains.

docker-agent and skills: true

docker-agent does not read the store. It scans its own directories, and two of them, ~/.claude/skills/ and ~/.agents/skills/, are also import sources. Docker Agent scans standard directories for SKILL.md files. It adds the name and the description of each skill to the system prompt:

In the agent file, skills: true loads every discovered skill, a list restricts it, and false turns it off. A list item that is local or an http:// or https:// URL is a source, and any other string is a skill name. A name that matches no discovered skill produces a warning at startup and is otherwise ignored. The agent needs the filesystem toolset to read skill files, as the toolsets section lists. context: fork in the front matter of a skill tells the agent to run the skill in an isolated sub-agent.

In a docker-agent sandbox

With docker-agent run --sandbox, the host paths above are invisible from the VM. Docker Agent builds a kit before the sandbox starts and mounts it read-only into the VM at the same path. It copies every SKILL.md that it finds on the host under <kit>/skills/<skill-name>/. Every text file passes a secret redaction step, and --no-kit turns the staging off. The end-to-end section shows the printed summary of what was staged.

A colleague sends you an agent file and one command to run it. You have no API key, only Docker Desktop with Model Runner, and you want proof that the file runs before you open a chat window.

When you finish this section, you can run an agent file with no terminal, read its event stream, and ask doctor which model auto picks.

What run takes

Agent reference: the first argument of docker-agent run. It is a .yaml, .yml, or .hcl file, a registry reference, an alias, or nothing. With nothing, run uses docker-agent.yaml, docker-agent.yml, or docker-agent.hcl from the current directory, or else a built-in default agent. coder is a second built-in agent, and alias add saves a name for a file or a reference together with run options such as --safety.

A registry reference behaves like a file. 24-run-ref.txt runs localhost:15000/m101/agent:v1 and prints the same answer as the local file, as share push and share pull shows. Each further argument is one user message, and the messages run as turns in order. A - reads the message from stdin.

--exec, --json, and --last

Headless run: run --exec, which writes to stdout and opens no TUI. --json writes one JSON event per line, and --last prints only the final answer. The capture runs the files agent with the same two messages in each form.

$ docker-agent run --exec --working-dir fixtures/repo --last --fake work/cassettes/18-files fixtures/agents/files.yaml 'List the files in the working directory.' 'How many lines does README.md have? Count them with a shell command.'
README.md has 1 line.
[exit 0]

{"message": "List the files in the working directory.", "session_id": "<uuid>", "session_position": 0, "timestamp": "<ts>", "type": "user_message"}
{"agent_name": "root", "timestamp": "<ts>", "tool_call": {"function": {"arguments": "{\"path\": \".\"}", "name": "list_directory"}, "id": "<call-id>", "type": "function"}, "tool_definition": …
{"agent_name": "root", "content": "The working directory contains 1 file: README.md (1 line).", "message_id": "<uuid>", "session_id": "<uuid>", "timestamp": "<ts>", "type": "agent_choice"}

The other event types of the file include team_info, toolset_info, tool_call_response, token_usage, and stream_stopped. The second turn shows the limit of a headless run. The model asked for shell with wc -l README.md, and the runtime raised tool_call_confirmation. With no terminal to answer it, the tool result was "The user rejected the tool call." The model then used read_file (the transcript). Permissions, --safety, and hooks explains why that call asked.

The model in every recording

The docs call ai/qwen3 the model that Docker Agent uses by default. With no Model Runner, doctor resolves auto to the 8B tag ai/qwen3:latest (16-doctor.txt). On the recording Mac, two pulls of that tag ended with a digest mismatch after the last 5.03 GB blob (25-model-pull-latest.txt). Every agent file of the kit therefore names ai/qwen3:4b, the 4B tag of the same repository. It is a thinking model, so it streams a few thousand reasoning tokens before each answer. --exec prints them, and the kit cuts them to one line such as [... 299 lines of model reasoning cut by run.py ...] (18-run-exec.txt).

doctor and models

doctor reports provider credentials, whether Docker Model Runner answers, the auto pick, and, with a file, the variables that file needs. It exits non-zero on an issue. The kit ran it once with no Docker daemon and once with Model Runner up.

$ docker-agent doctor
…
Docker Model Runner
  Status: unreachable: docker --config=$HOME/.docker --context=m101-no-daemon model status --json: …
…
Model auto-selection
  auto -> dmr/ai/qwen3:latest

Issues
  - no usable model: no provider credential was found and Docker Model Runner is unreachable; …
Error: 1 issue(s) found
[exit 1]

$ docker-agent doctor
…
Docker Model Runner
  Status: reachable, 1 model(s) pulled:
    - docker.io/ai/qwen3:4b

Model auto-selection
  auto -> dmr/docker.io/ai/qwen3:4b

No issues found.
[exit 0]

With no runner, auto still names dmr/ai/qwen3:latest, and the issue line says why nothing can run. With the runner up, auto takes the one pulled model, as the provider page says: auto-selection prefers a model that is installed locally. models list printed one row, dmr ai/qwen3:latest, even with no daemon (16-models.txt). setup is the interactive fix. Its four paths are a provider key in ~/.config/cagent/.env, a Model Runner pull, a custom OpenAI-compatible endpoint, and the Claude Code harness.

new

new asks questions and writes an agent file, and a description argument skips "the initial prompt". Its --model takes anthropic, openai, google, dmr, or a custom provider, and --max-iterations defaults to 20 for DMR (conflict C66). In the capture, new with a description and no controlling terminal stopped at /dev/tty and wrote no file (17-new-agent.yaml).

$ docker-agent new --model dmr/ai/qwen3:4b 'an agent that greets the user and names one fact about Docker sandboxes'  (in work/, without a controlling terminal)
…
Error: bubbletea: error opening TTY: bubbletea: could not open TTY: open /dev/tty: device not configured
[exit 1]

Figure 5.1 puts the pieces of one run on one page.

You open capture/fixtures/agents/files.yaml and find model: local on the agent, a local entry under models, and provider: dmr inside that entry. A second file, dmr.yaml, adds a providers block with a URL, and its run never reaches the recorder.

When you finish this section, you can follow an agent's model value to the endpoint it calls, and predict what auto picks.

The file and its schema

Agent file: a YAML or HCL document that matches agent-schema.json, the schema of Docker Agent v16. Its root allows 16 keys and requires one: agents, a map of agent configurations with at least one agent. A misspelled top-level key fails the load, because the parser rejects unknown top-level keys.

version is a string from "0" to "16" in the schema enum. The same docs page still gives 15 as the current version. The capture files declare "16" and load, so this manual follows the schema. When you load an older config, Docker Agent migrates it to the latest schema. The agent that share pull fetched from agentcatalog/pirate declares version: "2" and names openai/gpt-4.1 inline (16-share-pull-agent.yaml).

version: "16"

agents:
  root:
    model: local
    description: Lists the files of a small repository and counts lines.
    instruction: |
      You answer questions about the files in the working directory.
      Use the tools to look; never guess. Answer in one sentence that
      names the files and gives the line count.
    max_iterations: 8
    toolsets:
      - type: filesystem
      - type: shell

models:
  local:
    provider: dmr
    model: ai/qwen3:4b
    temperature: 0

Agent keys

Agent: one entry under agents, named by its key. The first agent of the team runs unless --agent names another. The schema AgentConfig lists the keys, and these are the ones the capture files use or rely on.

Model references

Model reference: the value of model on an agent. It takes five forms:

• provider/model inline, such as dmr/ai/qwen3 in greeter.yaml.
• a name under models, such as local, with provider, model, and parameters such as temperature: 0.
• a first_available list: at load time, Docker Agent picks the first candidate that has its credentials configured.
• an alloy: two references with a comma between them, which the runtime alternates in one conversation.
• auto: the first cloud provider that has a configured credential, then a pulled Model Runner model.

run --model [agent=]provider/model replaces the reference for one run. On the recording Mac, doctor resolved auto to dmr/docker.io/ai/qwen3:4b with only the 4B tag pulled (25-doctor.txt). With no Model Runner, it named dmr/ai/qwen3:latest and reported no usable model (16-doctor.txt).

providers and the Model Runner endpoint

Provider definition: an entry under providers with an underlying provider (default openai), a base_url, a token_key, and defaults that its models inherit.

version: "16"

providers:
  runner:
    provider: dmr
    base_url: http://localhost:12434/engines/llama.cpp/v1

models:
  qwen:
    provider: runner
    model: ai/qwen3:4b
    temperature: 0
…

files.yaml names provider: dmr with no base_url, and then Docker Agent finds the DMR endpoint by itself. It runs docker model status --json, which 16-dry-run.txt prints inside its error when no Docker daemon answers. An eval container has no docker CLI, so the same discovery fails there, as eval shows.

With an explicit base_url, dmr.yaml answered Hello (the capture). That run is live in every capture, because an explicit base_url bypasses the --record proxy and leaves the cassette empty (kit notes). Set base_url when discovery cannot work, and leave it out when you want a cassette.

Provider ids changed too. doctor prints fireworks-ai, togetherai, and moonshotai, and the docs Models table lists fireworks, together, and moonshot. This manual prints the ids that doctor prints (conflict C58), and the providers table has the rest. A named patch under flavors changes any of these blocks at run time with --flavor, and the capture ran none.

Your agent answers questions about a repository from memory, and you suspect it never received a file tool. The agent file says filesystem, but the model sees tool names, not toolsets.

When you finish this section, you can list the tools an agent gives its model, call one without a model, and choose an MCP form.

The 27 types

Toolset: one entry under an agent's toolsets, with a type and options, that the runtime turns into one or more tools. docker-agent toolsets prints 27 types, and the schema Toolset enum has the same 27.

$ docker-agent toolsets
TYPE                SUMMARY
…
background_agents   Dispatch work to sub-agents concurrently and collect results
…
filesystem          Read, write, list, search, and navigate files and directories
…
mcp                 Extend agents with external tools via the Model Context Protocol
mcp_catalog         Discover and activate remote MCP servers from the Docker MCP Catalog
…
plan                Shared persistent scratchpad for multi-agent collaboration
…
shell               Execute shell commands in the user's environment
…
[exit 0]

transfer_task and handoff are not types. The docs built-in table lists both, the schema enum and the CLI list leave them out, and sub_agents and handoffs inject them (conflict C56). The same docs table lists session_plan, which the CLI does not print, and leaves out environment and file. The toolsets table follows the CLI.

From toolsets to tools

files.yaml declares two toolsets, filesystem and shell. Every toolset_info event of its run reports "available_tools": 10 (18-run-json.ndjson). The request in the cassette 18-files.yaml lists them: nine filesystem tools from directory_tree to remove_directory, then shell. The model chose list_directory and read_file from that list.

debug toolsets FILE --json prints the same names and schemas with no model. For guarded.yaml it prints one tool:

[
  {
    "agent": "root",
    "tools": [
      {
        "name": "shell",
        "category": "shell",
…
        "parameters": {
          "additionalProperties": false,
          "properties": {
            "cmd": {
              "description": "Shell command",
              "type": "string"
            },
            "cwd": {
              "description": "Working directory (default \".\")",
              "type": "string"
            },
            "timeout": {
              "description": "Timeout in seconds (default 30)",
              "type": "integer"
            }
          },
…
        "annotations": {
          "idempotentHint": false,
          "readOnlyHint": false,
          "title": "Shell"
        },
…

debug tool FILE TOOL JSON calls one tool with no model turn, and the call has real side effects and skips the other hooks and approval checks. In 20-debug-tool.txt, shell with {"cmd":"echo m101-direct"} printed m101-direct. Use it to test a tool before any model calls it.

Keys every toolset shares

Tool filter: a key that narrows what a toolset gives the model. tools keeps only the listed names, and readonly keeps only tools whose annotations carry a read-only hint. defer hides tools until the model finds them with search_tool and add_tool. instruction replaces the toolset's built-in instructions unless the text contains {ORIGINAL_INSTRUCTIONS}. model names the model for the turn after a tool result. Since v1.148.0 a complete tool result is bounded to 50 KiB.

The readOnlyHint: false on shell matters again in permissions, --safety, and hooks.

The mcp type

MCP toolset: a toolset with type: mcp that connects to one MCP server and gives its tools to the agent. The docs name three forms:

• ref: docker:duckduckgo runs a catalog server in a container through the MCP Gateway.
• command, args, and env start a local process over stdio, and a missing binary is installed into ~/.cagent/tools/bin/ from the aqua registry.
• remote.url with transport_type set to streamable or sse reaches a server over the network, with optional headers.

lifecycle.profile sets reconnects for each mcp toolset: resilient by default, strict, or best-effort. A top-level mcps entry holds a server definition that agents reference as {type: mcp, ref: <name>}. A top-level toolsets entry, named in use_toolsets, does the same for any type.

No mcp toolset ran in this edition's captures, so the three forms come from the docs and the schema. Whether ref: docker: needs Docker Desktop's MCP Toolkit stays open (conflict C73). The sandbox side of MCP is sbx mcp add, load, and --static-mcp. An agent served as an MCP server is serve mcp and serve acp.

You want a coordinator that asks a writer for one sentence and then lets a reviewer answer the user. One agent file can say both things: a delegation that comes back, and a move that does not.

When you finish this section, you can choose between sub_agents, handoffs, and background_agents, and read each one in an event stream.

The team file

version: "16"

agents:
  root:
    model: local
    description: Coordinates a writer and a reviewer.
    instruction: |
      You coordinate two colleagues and never write text yourself.
      For every request: first call transfer_task to ask the writer for
      the text, then call handoff to pass the conversation to the reviewer.
    max_iterations: 6
    sub_agents: [writer]
    handoffs: [reviewer]
    toolsets:
      - type: background_agents

  writer:
    model: local
    description: Writes one sentence on a given topic.
…
    max_iterations: 3

  reviewer:
    model: local
    description: Reviews the sentence it receives.
…

All three agents use the model local, which is dmr/ai/qwen3:4b. Neither transfer_task nor handoff appears under toolsets, because the two lists inject them (conflict C56).

transfer_task: a child in a sub-session

Delegation: a call of transfer_task with agent, task, and expected_output, which sub_agents adds to the parent. The call waits until the sub-agent returns its result, and that result becomes the response of the tool.

user: Ask the writer for one sentence about microVMs.
root -> tool_call transfer_task {"agent": "writer", "task": "Generate one sentence about microVMs", "expected_output": "A single sentence describing microVMs"}
agent_switching: {"agent_name": "writer", "switching": true, "from_agent": "root", "to_agent": "writer"}
writer: MicroVMs are lightweight virtual machines that provide strong isolation and security for applications with minimal resource overhead.
stream_stopped (stop, normal)
sub_session_completed: {"agent_name": "root", "parent_session_id": "<uuid>", "sub_session": {"id": "<uuid>", "origin": "run", "title": "Transferred task", "messages": [{"message": {"agent_name": "", "message": {"role": "system", "content": "You are a member of a team of agents. Your goal is to complete the following task:\n\n<task>\nGenerate one sentence about microVMs\n</task>…
agent_switching: {"agent_name": "root", "switching": false, "from_agent": "writer", "to_agent": "root"}
root <- tool_call_response Transfer Task: MicroVMs are lightweight virtual machines that provide strong isolation and security for applications with minimal resource overhead.
root -> tool_call handoff {"agent": "reviewer"}
root <- tool_call_response Handoff Conversation: The agent root handed off the conversation to you. …
reviewer: APPROVED: MicroVMs are lightweight virtual machines that provide strong isolation and security for applications with minimal resource overhead.
stream_stopped (stop, normal)
user: Now hand the conversation to the reviewer.
reviewer: APPROVED: MicroVMs are lightweight virtual machines that provide strong isolation and security for applications with minimal resource overhead.
stream_stopped (stop, normal)

The writer never saw the user's message. Its sub-session starts with a system message that holds <task> and <expected_output>. An implicit user message follows, "Please proceed." The sub-session ran under the writer's own max_iterations: 3, with "tools_approved": false. Then agent_switching returned control to root, and the sentence came back as the tool response.

transfer_task is the one tool that is always approved without a prompt, and the capture agrees: the call raised no confirmation under --exec. A delegation to an agent already in the chain fails, and the depth is capped at 10 nested delegations. A sub_agents entry can also be a registry reference. Its tag is resolved again on every run unless you pin it to a digest.

The session move

Session move: a call of handoff with one argument, agent, which handoffs adds. The named agent becomes the active agent and sees the whole conversation history. In the capture, root called it in its next model turn, after the sentence came back. The tool response told reviewer which tools and agents it can use, and reviewer answered the user.

The second message shows the move. It went straight to reviewer, and the transcript has no root line after the move. force_handoff makes the same move on every final response without a tool call.

background_agents

Background agent: a sub-agent task that run_background_agent starts, which returns a task id at once. list_background_agents, view_background_agent, and stop_background_agent follow it, and the target must be in the caller's sub_agents.

user: Run the writer as a background agent on the topic microVMs, wait for it, and repeat its sentence.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\", \"expected_output\": \"A single sentence about microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
…
stderr: Error: Agent terminated: detected 5 consecutive identical calls to run_background_agent. This indicates a degenerate loop where the model is not making progress.

Under --exec with no --safety, the call itself asked for approval, and with no terminal it was rejected. The model sent the same call again until the runtime stopped the run with exit 1. The limit is max_consecutive_tool_calls, and 0 means the default of 5. Inside a running task, a tool call that would normally ask the user for approval is denied automatically. A headless coordinator therefore needs an allow rule for run_background_agent and for the tools its sub-agents call. The capture did not test that.

The kit asks for one tool call per message. A turn with two parallel calls cannot be replayed from a cassette, as session.db, sessions diff, and eval explains.

Your agent runs in CI with --exec, and nobody watches the terminal. You want echo to run, rm never to run, and every other call to fail closed unless its label is safe. The agent file and one flag can say that, but only for calls that go through docker-agent.

When you finish this section, you can write permissions patterns, pick a --safety mode for an unattended run, and predict what a pre_tool_use hook changes.

The same page says that the restricted mode is an extra layer against unwanted tool calls, not a security boundary. For isolation, run the agent in a sandbox, as docker-agent run --sandbox shows.

The guarded agent

version: "16"

agents:
  root:
    model: local
    description: Runs shell commands under a permission list and a hook.
    instruction: |
      Run exactly the shell commands the user lists, one tool call per
      command, in the given order. Then report each command and its
      result or refusal in one line each.
    max_iterations: 8
    toolsets:
      - type: shell
    hooks:
      pre_tool_use:
        - matcher: shell
          preempt_yolo: true
          hooks:
            - type: command
              command: ./fixtures/hooks/log-hook.sh
              env:
                M101_HOOK_LOG: ./work/hook-stdin.jsonl

permissions:
  allow:
    - "shell:cmd=echo*"
  deny:
    - "shell:cmd=rm*"
…

Permission pattern: a tool name glob with optional argument conditions, such as shell:cmd=rm*, in an allow, ask, or deny list. Patterns from the agent file and from settings.permissions in the user config merge, and a deny from either side wins.

Safety mode: what the runtime does with a call that no pattern matched. It reads the call's label, safe, destructive, or unknown, and the mode decides:

--yolo is the same as --safety autonomous. A session that never chooses a mode keeps the old default: read-only tools run without a prompt, and every other tool asks. That is why the wc -l call in run, new, and doctor asked although its label was safe, because shell carries readOnlyHint: false.

Three calls in two modes

The kit sent the same three messages under --safety strict and --safety restricted, one command per message, with no terminal to answer a prompt.

The patterns behaved the same in both modes, and only the unmatched pwd changed. Under restricted, the mode allowed the safe label. Under strict, the runtime raised tool_call_confirmation, and the empty terminal turned it into a rejection (20-strict.txt, 20-restricted.txt).

The order, and what a hook can change

The docs give one order for every call:

1. preempt_yolo pre_tool_use hooks run first, and no mode or allow rule can bypass their deny or ask.
2. A deny pattern blocks the call.
3. An allow pattern approves it.
4. An ask pattern prompts the user.
5. With no match, the safety mode applies to the call's label.
6. On a mode ask, default pre_tool_use hooks can allow, deny, or ask.
7. With no decision, the user is asked.

Hook: a command, builtin, model, or evaluator entry that runs at a named event. A command hook reads one JSON object on stdin and can answer with JSON on stdout. Exit code 2 blocks, and the default timeout is 60 seconds.

{"agent_name": "root", "cwd": "$CAPTURE", "hook_event_name": "pre_tool_use", "safety_policy": "restricted", "session_id": "<uuid>", "tool_input": {"cmd": "rm -rf work/m101-nothing"}, "tool_name": "shell", "tool_use_id": "<call-id>"}

log-hook.sh appends that line to a file and prints "permission_decision":"allow". The stream shows it as pre_tool_use_pre_yolo with "allowed": true on all three calls, yet rm was denied and strict still asked for pwd. From a preempting hook, an allow verdict is only advice. Its deny or ask would have ended the call.

Two more hooks run on every call: tool_input_transform and tool_response_transform appear in each stream, although no file declares them. redact_secrets, true by default, installs a builtin on those events. A hook can also run several times at once. When one message asked for three commands, the hook ran three times at once. Two runs appended to the log file together (kit notes). Write each record in one write.

You changed one line of an agent's instruction, and you want to know whether it still does the same work. A live model words every answer differently, so you need records that you can replay and compare.

When you finish this section, you can replay a run from a cassette, compare two runs by tool calls, and score an agent with eval.

session.db

Session: the record of a conversation, with every message, tool call, sub-agent run, and cost. It lives in session.db under the data directory, ~/.cagent unless --data-dir or -s points elsewhere. --session -1 resumes the newest session by creation time.

$ sqlite3 work/data/session.db .tables  (python sqlite3)
generated_media_blobs generated_media_manifest migrations session_items sessions sqlite_sequence
…
$ sqlite3 work/data/session.db 'pragma table_info(sessions)'  (12 rows)
id created_at tools_approved input_tokens output_tokens title cost send_user_message max_iterations working_dir starred permissions agent_model_overrides custom_models_used thinking parent_id instruction_context safety_policy attributes origin

$ sqlite3 work/data/session.db 'select id, title from sessions order by created_at desc limit 5'
<uuid> | Running agent
…

The table held 12 sessions: ten runs, and the two Transferred task sub-sessions of the team runs, which carry a parent id (19-transcript.txt). Each session stores its safety_policy, and session_items holds the messages. The five newest, all --exec runs, are titled Running agent, not a title made from the first message as the docs describe.

Cassettes: --record and --fake

Cassette: a YAML file of the HTTP exchanges between docker-agent and the model. --record writes it, and --fake replays it with no model at all. 18-cassette-head.txt shows the format: version: 2, then interactions, each with a request to localhost:12434 and the streamed reply.

    def start_recording(self, name):
        if not self.record_cassettes and os.path.exists(cassette_path(name)):
            return None
        self.recorded.append(name)
        return ["--models-gateway", f"{DMR_URL}/engines", f"--record={CASSETTE_WORK}/{name}"]
…
def replay(name):
    return ["--fake", f"{CASSETTE_WORK}/{name}"]

The recording found four rules that the help does not state (kit notes). --record takes its value only as --record=PATH, and a separate word is read as the agent reference. The path is relative to --working-dir, and .yaml is appended. With the dmr provider the recording proxy answers 400 unless the run also has --models-gateway http://localhost:12434/engines.

Replay matches each request by its body. When one turn issues two tool calls, the runtime runs them in parallel and appends the results in completion order. The next request body then differs, and the replay answers 500, "requested interaction not found". The kit therefore sends one tool call per message.

sessions diff

The comparison looks at the sequence of tool calls, not at the prose of the assistant, and the report stops at the first divergence.

$ docker-agent sessions diff -1 -2
Error: unknown shorthand flag: '1' in -1
[exit 1]

$ docker-agent sessions diff -- -1 -2
Comparing -1 (5 turns) against -2 (5 turns)

✅ Identical behaviour across all 5 turns.
[exit 0]

$ docker-agent sessions diff --fail-on-divergence -- -1 -3
Comparing -1 (5 turns) against -3 (6 turns)

❌ First divergence at turn 0 (after 0 matching turn(s)).
   -1 called:
     list_directory({"path": "."})
   -3 called:
     shell({"cmd": "echo m101-ok"})

Everything after this point is downstream of the divergence and is not compared.
Error: sessions diverged
[exit 1]

The help's own example, sessions diff -1 -2, fails, because the parser reads -1 as a flag. Put -- before the references. -1 and -2 are two replays of files.yaml (21-two-runs.txt), with five turns each, one per model reply in 18-transcript.txt. -3 is the restricted run of guarded.yaml, which called shell first. --json printed {"turns_a": 5, "turns_b": 5, "turns_matched": 5} for the identical pair (21-sessions-diff.json).

eval

Eval session: a JSON session with a user message, the expected tool calls, and an evals block. The block holds relevance statements, a size, and a working_dir. eval replays each one in a container and scores tool-call F1, relevance by a judge model, and size.

The capture needed three tries with --judge-model dmr/ai/qwen3:4b. Plain, both evals failed with exec: "docker": executable file not found in $PATH, because the image docker/docker-agent:1.149.0 has no docker CLI to find Model Runner (22-eval.txt). With --models-gateway http://model-runner.docker.internal/engines, the judge check failed first with HTTP 403. The docs explain why: the LLM judge runs on the host, not in the eval container, and the host cannot reach that name (22-eval-gateway.txt). With -e DOCKER_AGENT_MODELS_GATEWAY=…, only the containers changed, and both evals ran.

$ docker-agent eval fixtures/agents/files.yaml fixtures/evals --judge-model dmr/ai/qwen3:4b -c 1 -e DOCKER_AGENT_MODELS_GATEWAY=http://model-runner.docker.internal/engines --output work/eval-results-container-env
…
✓ Count the lines of README.md ($0.000000)
  ✓ size S
  ✓ tool calls
  ✓ relevance 1/1
✗ List the files in the working directory ($0.000000)
  ✓ size S
  ✓ relevance 1/1
  ✗ tool calls score 0.67
…
✅          Sizes: 2/2 passed (100.0%)
✅     Tool Calls: 83.3% avg F1 (2 evals)
✅      Relevance: 2/2 passed (100.0%)
…

The second eval expected one list_directory call, and the model added a shell call after it, so F1 fell to 0.67 (22-eval-run-container-env.json). Both eval sessions ran with "safety_policy": "autonomous". The help defaults are -c 10 and the judge openai/gpt-5.6-terra, and the docs table says the number of CPUs and anthropic/claude-opus-5. This manual follows the help (conflict C65). The output directory held <run>.db, <run>.json, and <run>.log, without the -sessions.json file that the docs list (22-eval-results-ls-container-env.txt).

Your agent file answers well in a terminal, and now a web page and a CI job must call it over HTTP. The page wants every event of a turn, and the CI job speaks only the OpenAI chat format.

When you finish this section, you can start both servers on one agent file, run one turn through each, and read the event stream.

One agent file, five servers

The a2a, acp, api, and mcp commands moved under serve in v1.23.4, and v1.53.0 added chat. The help of v1.149.0 lists all five. This part serves one small file all five ways. Its one agent, root, answers every message with the word pong:

version: "16"

agents:
  root:
    model: local
    description: Answers every message with the word pong.
    instruction: Reply with exactly the word pong and nothing else.

models:
  local:
    provider: dmr
    model: ai/qwen3:4b
    temperature: 0

serve api: a session, then a run

serve api: the command that serves your agents through a REST-style API with Server-Sent Events (SSE) streaming. It listens on 127.0.0.1:8080, and an empty --auth-token means no authentication. --max-request-size rejects a body over 1 MiB with HTTP 413, and --session-workingdir-root confines the working_dir of new sessions.

The session database has a different default here. serve api -s writes session.db in the current directory, while run, serve a2a, and serve acp use <data-dir>/session.db (conflict C63). The capture passed -s work/api-session.db and --fake work/cassettes/23-api, so a recorded cassette gave the model answer (the capture).

GET /api/agents HTTP/1.1
…
    "name": "pong",
    "description": "Answers every message with the word pong.",
    "multi": false
…
POST /api/sessions HTTP/1.1
…
{}
…
  "id": "<uuid>",
  "origin": "run",
…
  "tools_approved": false,
…
POST /api/sessions/<uuid>/agent/pong HTTP/1.1
…
Accept: text/event-stream
…
      "role": "user",
      "content": "ping"
…
HTTP/1.1 200 OK
…
Content-Type: text/event-stream

The agent identifier in the path is the file name without .yaml, so pong, while the events name the agent root. The run body is a messages array with an optional model field, which sets a model override for that agent in the session. A new session has tools_approved: false. A tool call then raises tool_call_confirmation, and the client answers with POST /api/sessions/:id/resume.

The run stream

data: {"agent_name": "root", "available_agents": [{"description": "Answers every message with the word pong.", "model": "ai/qwen3:4b", "name": "root", "provider": "dmr"}], "current_agent": "root", "timestamp": "<ts>", "type": "team_info"}
data: {"agent_name": "root", "available_tools": 0, "loading": false, "timestamp": "<ts>", "type": "toolset_info"}
data: {"message": "ping", "session_id": "<uuid>", "session_position": 0, "timestamp": "<ts>", "type": "user_message"}
data: {"agent_name": "root", "session_id": "<uuid>", "timestamp": "<ts>", "type": "stream_started"}
data: {"agent_name": "root", "available_tools": 0, "loading": false, "timestamp": "<ts>", "type": "toolset_info"}
data: {"agent_name": "root", "description": "Answers every message with the word pong.", "model": "dmr/ai/qwen3:4b", "timestamp": "<ts>", "type": "agent_info"}
data: {"agent_name": "root", "content": "pong", "message_id": "<uuid>", "session_id": "<uuid>", "timestamp": "<ts>", "type": "agent_choice"}
data: {"agent_name": "root", "session_id": "<uuid>", "timestamp": "<ts>", "type": "message_added"}
data: {"agent_name": "root", "session_id": "<uuid>", "timestamp": "<ts>", "type": "token_usage", …}
data: {"agent_name": "root", "finish_reason": "stop", "reason": "normal", "session_id": "<uuid>", "timestamp": "<ts>", "type": "stream_stopped"}

The docs list eight event types, from stream_started to error. The capture adds six more: team_info, toolset_info, user_message, agent_info, message_added, and token_usage. The pong agent has no tools, so no tool_call frame appears. The last request of the file reads the session back, and the stored assistant message keeps the model's reasoning_content beside the answer (the capture). Figure 6.1 draws the whole exchange.

A run is one request, and the session outlives it. /steer injects messages into a running turn, /followup queues them with an optional Idempotency-Key, and /fork copies a session up to a user message. GET /api/sessions/:id/events is a session-wide stream that resumes from Last-Event-ID or ?since=. An interactive docker-agent run --listen ADDR serves the same control plane, with a fixed 1 MiB body limit and no --auth-token. The help does not list that flag, and each such run writes <data-dir>/runs/<pid>.json for discovery.

serve chat: the OpenAI-compatible subset

serve chat: the command that serves the agent through an OpenAI-compatible API at /v1/chat/completions and /v1/models. The model id is the agent name, so the capture lists root, the name inside the file, where serve api used pong, the file name.

GET /v1/models HTTP/1.1
…
Authorization: Bearer m101-chat-key
…
      "id": "root",
…
      "owned_by": "docker-agent",
…
POST /v1/chat/completions HTTP/1.1
…
        "role": "assistant",
        "content": "pong"
…
HTTP/1.1 401 Unauthorized
…
    "message": "missing or invalid bearer token",

By default the server keeps no conversation, so each request carries the full history. --conversations-max caches up to N conversations keyed by X-Conversation-Id, and --conversation-ttl evicts them after 30 minutes. A failed turn leaves a cached conversation unchanged, so a client can retry with the same id. With stream: true in the body, the reply is an SSE stream of chat.completion.chunk deltas. --max-idle-runtimes keeps four idle runtimes per agent, and --request-timeout bounds each request at five minutes, model and tool calls included. A listener that is not on loopback needs --api-key, --api-key-env, or --insecure-no-auth.

Your MCP client already calls tools, and your editor already talks to coding agents. Neither of them reads an agent file. serve mcp turns the agent into a tool for the first, and serve acp turns it into an editor agent for the second.

When you finish this section, you can serve an agent as an MCP tool, read its schema, and open an ACP session from an editor.

serve mcp: one agent, one tool

serve mcp: starts an MCP server that serves the agent over the Model Context Protocol, with stdio transport by default. --http switches to streaming HTTP on 127.0.0.1:8081. Without -a, every agent of a team file becomes its own tool, and --tool-name renames the tool when one agent is exposed.

--attach exposes the session of a running TUI, found by pid, address, or session id. --mcp-keepalive works over stdio only, while --auth-token, --insecure-no-auth, and --safety work with --http only. Over HTTP the safety policy defaults to restricted.

The capture ran serve mcp fixtures/agents/pong.yaml --http --listen 127.0.0.1:8081 --tool-name pong, with the file of serve api and serve chat:

POST /mcp HTTP/1.1
…
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-07-28",
…
Content-Type: text/event-stream
…
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{},"tools":{"listChanged":true}},"protocolVersion":"2025-11-25","serverInfo":{"name":"docker agent","version":"v1.149.0"}}}
…
data: {"jsonrpc":"2.0","id":2,"result":{"ttlMs":0,"cacheScope":"public","tools":[{"annotations":{"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":true,…"inputSchema":{…"properties":{"message":{"description":"the message to send to the agent","type":"string"}},"required":["message"],"type":"object"},"name":"pong","outputSchema":{…
…
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"response\":\"pong\"}"}],"structuredContent":{"response":"pong"}}}

The client asked for revision 2026-07-28, which v1.129.0 added together with a stateless Streamable HTTP transport. The server answered 2025-11-25, so read the version from the result, never from your request. No response carried an Mcp-Session-Id header. Each answer came as one SSE message event, and the notification got 202 Accepted (the capture).

The tool takes one string, message, and returns structuredContent.response, with the same text as a JSON string in content. Its annotations mark it read-only and idempotent, and its title is the agent's description. The tools/call answer came as one event after the whole turn, with no progress notification before it. The kit README adds that the server answered on / as well as /mcp (the capture). The docs register the stdio form in Claude Code with claude mcp add --transport stdio, followed by -- docker agent serve mcp and the agent reference.

serve acp: JSON-RPC lines to an editor

serve acp: a server that talks over stdio, the standard input and output. The editor spawns docker-agent serve acp FILE, writes JSON-RPC requests to its stdin, and reads responses and notifications from its stdout. Sessions persist in <data-dir>/session.db unless -s names another file. A team file works as well, and the docs say its sub-agents need no change for ACP.

>> {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": 1, …}}
<< {"id": 1, "jsonrpc": "2.0", "result": {"agentCapabilities": {"auth": {"logout": {}}, "loadSession": true, …, "agentInfo": {"name": "docker agent", "title": "docker agent", "version": "v1.149.0"}, …, "protocolVersion": 1}}
>> {"jsonrpc": "2.0", "id": 2, "method": "session/new", "params": {"cwd": "$CAPTURE", "mcpServers": []}}
<< {"jsonrpc": "2.0", "method": "session/update", "params": {"sessionId": "<uuid>", "update": {"availableCommands": [{"description": "Summarize and compact session history", …, "name": "compact"}, {"description": "Display current context token usage and session cost", "name": "usage"}], "sessionUpdate": "available_commands_update"}}}
<< {"id": 2, "jsonrpc": "2.0", "result": {"configOptions": [{"category": "mode", "currentValue": "default", …}], "modes": {…, "currentModeId": "default"}, "sessionId": "<uuid>"}}

initialize returns agentCapabilities: loadSession, MCP servers over HTTP and SSE, audio, image, and embedded-context prompts, and the session operations close, delete, list, and resume. It offers one auth method, host-credentials, which v1.144.0 added together with session deletion. Before the session/new result, a session/update notification lists the slash commands. Release v1.143.0 announced /compact, /usage, and /new, and the captured list has no new.

The session starts in mode default, which auto-approves read-only tools and asks for the rest. The mode list adds default to the four values of --safety. A client changes the mode with session/set_config_option or the older session/set_mode. The capture stops at session/new, so it shows no prompt turn over ACP. The docs sketch the host side with a method agent/run and call that code pseudocode. Use the method names of the capture.

For the protocol under serve mcp, read the MCP transports lesson.

A planner on another team speaks A2A and wants to give your agent work. It will fetch a card, send one message, and read a task, as the A2A 101 manual teaches in SendMessage.

When you finish this section, you can serve an agent over A2A, call it with 1.0 names, and predict where a strict client objects.

The card at the well-known path

serve a2a: starts an A2A server that serves the agent over the Agent-to-Agent protocol. It listens on 127.0.0.1:8082, and -a defaults to the first agent of the team, where the legacy plugin named root (conflict C64). --auth-token covers the card and every invocation, and a listener off loopback needs it or --insecure-no-auth. Sessions default to the restricted safety policy.

The Docker Agent docs name neither the card path nor the protocol version (conflict C71). The capture found the card at /.well-known/agent-card.json. /.well-known/agent.json answered 404, and so did a POST to / (the capture).

{
  "supportedInterfaces": [
    {
      "url": "http://127.0.0.1:8082/invoke",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": [],
  "defaultOutputModes": [],
  "description": "Answers every message with the word pong.",
  "name": "pong",
  "skills": [
    {
      "description": "Answers every message with the word pong.",
      "id": "pong_",
      "name": "",
      "tags": [
        "llm",
        "docker agent"
      ]
    }
  ],
  "version": "v1.149.0"
}

The card names the file, pong, where serve chat used the agent name root. Its one skill has the id pong_ and the description of the agent. The response also carried Access-Control-Allow-Origin: *, although the run set no --cors-origin and the help says "empty disables CORS".

SendMessage and GetTask

The card points to one JSON-RPC interface, http://127.0.0.1:8082/invoke, at protocol version 1.0. The capture sent SendMessage there with A2A-Version: 1.0 and no configuration:

POST /invoke HTTP/1.1
…
A2A-Version: 1.0
…
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "m101-0001",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "ping"
        }
…
  "result": {
    "task": {
…
      "artifacts": [
        {
          "artifactId": "<uuid>",
          "metadata": {
            "adk_partial": true
          },
          "parts": [
            {
              "data": {},
…
        {
          "artifactId": "<uuid>",
          "parts": [
            {
              "text": "pong"
…
      "status": {
        "state": "TASK_STATE_COMPLETED",
…
  "method": "GetTask",
  "params": {
    "id": "<uuid>"
  }

The send returned a task already in TASK_STATE_COMPLETED, and GetTask returned the same task with its history (the capture). The answer pong sits in the second artifact, and history keeps only the user message. The server made one live call to ai/qwen3:4b, because serve a2a has no --fake. The card sets streaming: true, so SendStreamingMessage is on offer, but the capture did not call it. Figure 6.3 draws the exchange.

Sessions persist in the session database since v1.59.0, and a client resumes one through /invoke with its A2A context. A context id that collides with another session is rejected, and that session stays unchanged. Sessions that older binaries stored are labelled run and cannot be resumed over A2A.

Where it differs from A2A 1.0.1

The A2A 101 manual of this repository states the 1.0.1 rules: AgentCard fields for the card and SendMessage for the call. The table holds each captured value against those rules.