Each binary owns one thing: sbx owns the microVM, its proxy, and its secret store, and docker-agent owns the loop between a model, tools, and sub-agents.
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 {{docs-sbx Isolation layers}}, 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 {{docs-sbx Develop and test locally}}.
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 {{docs-sbx Install Docker Sandboxes}}. 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 {{help-sbx sbx daemon log-level set}}. Every outbound TCP connection from the sandbox goes through a proxy on your host {{docs-sbx Architecture}}. On macOS, sbx secret set keeps each key in the system Keychain {{docs-sbx Where secrets are stored}}. 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 shows who owns what.
Original source
id: fig-1-1
kind: layers
title: what sbx owns and what docker-agent owns
claim: sbx owns every layer from the daemon to the guest kernel, and docker-agent owns its binary, its files, and the loop inside the guest.
caption: Read each column from the host band down through the dashed hypervisor line. The kernel and engine come from m101-demo in the guest and environment captures. The docker-agent column comes from the sandbox run captures.$ 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
…Original source
title: the command groups of sbx
source: capture/out/01-help-sbx.txt
lang: text
note: Each group is cut to the commands this part names, and the other groups and the flags are cut.
---
$ 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 {{help-sbx sbx run}}. 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 {{rel-sbx v0.43.0}}. sbx create docker-agent also answers to the alias cagent {{help-sbx sbx create docker-agent}}. shell gives you a Bash login shell in a sandbox, with no agent binary installed {{docs-sbx Shell}}. 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 {{docs-agent Docker Agent}}. 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
…Original source
title: the command groups of docker-agent
source: capture/out/01-help-docker-agent.txt
lang: text
note: Cut to the core group and four of the advanced commands. The diagnose group, the other commands, and the flags are cut.
---
$ 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 {{docs-sbx Docker Agent}}. 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 {{docs-agent Sandbox Mode}}, and --template defaults to docker/docker-agent-sbx-templates:latest {{help-agent docker-agent run}}. Two paths use two images, as conflict C61 rules. The capture kit recorded only the second path, and the next section follows it.
Original source
id: fig-1-2
kind: comparison
title: two ways to start docker-agent in a sandbox
claim: Both paths end with docker-agent in a microVM, but sbx run starts from a template image and docker-agent run --sandbox starts from your agent file.
caption: Read across each row. Path A comes from the docs page Docker Agent under docs-sbx, because no capture runs it. Path B comes from the sandbox run captures.Two agent binaries on one machine
Docker Desktop 4.94.0 bundles Docker Agent v1.144.0 {{docs-desktop 4.94.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 {{docs-agent Docker Agent}}.
$ 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]Original source
title: two agent binaries on the capture Mac
source: capture/out/29-docker-agent-plugin.txt
lang: text
note: Nothing is cut.
---
$ 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 {{docs-agent Docker Agent}}. Gordon is outside this manual.
Original source
- Install `sbx`, sign in with `sbx login`, and run sandboxes without Docker Desktop.
- Type `docker-agent`, and check `docker agent version` before you follow a hint that names `docker agent`.
- Start with `sbx run docker-agent` for a template run, or `docker-agent run --sandbox` for your own agent file.Sources: help-sbx sbx run, sbx create, sbx create docker-agent, sbx daemon log-level set (research/sources/help-sbx.md); help-agent docker-agent run (research/sources/help-docker-agent.md); docs-sbx Isolation layers, Develop and test locally, Install Docker Sandboxes, Architecture, Where secrets are stored, Shell, Docker Agent (research/sources/docs-sandboxes.md); docs-agent Docker Agent, Sandbox Mode (research/sources/docs-docker-agent.md); docs-desktop 4.94.0 (research/sources/docs-desktop-release-notes.md); rel-sbx v0.43.0 (research/sources/sbx-releases.md); research/conflicts-register.md rows C9, C15, C48, C61, C72; capture/out/01-help-sbx.txt, 01-help-docker-agent.txt, 02-daemon-status.txt, 02-diagnose.txt, 04-env.txt, 04-guest.txt, 16-sandbox-list.txt, 16-toolsets.txt, 27-sandbox-run.txt, 27-inside.txt, 29-docker-agent-plugin.txt, 29-docker-plugins.txt, 29-docker-sandbox.txt