Manuals / Docker Sandboxes and Docker Agent 101 / Part 1 · The Two Products on One Page
1.1

sbx and docker-agent

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, 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.

Fig. 1.1what sbx owns and what docker-agent ownslayers
What sbx owns and what docker-agent owns Two columns over two bands. In the host band, sbx owns the sbx v0.47.0 CLI, the sandboxd daemon on its socket, the macOS Keychain that holds secrets, and the proxy on gateway.docker.internal:3128. docker-agent owns the docker-agent v1.149.0 binary, the agent file, the staged kit under sandbox-kits, and the persistent allowlist with localhost:12434. A dashed line marks the hypervisor. In the guest band, sbx owns the Linux 7.0.14 kernel, the private Docker Engine 29.8.1, the virtiofs workspace mount at the same path, and the environment with proxy variables and proxy-managed keys. docker-agent owns only the loop inside: the docker-agent process, its filesystem and shell tools, and its model call. owned by sbx owned by docker-agent HOST · MACOS 26.2 ARM64 sbx v0.47.0 the CLI you type sandboxd sandboxd.sock Keychain sbx secret set proxy :3128 policy, key swap docker-agent v1.149.0, Homebrew agent file files-sandbox.yaml sandbox-kits/<hash> the staged kit allowlist localhost:12434 Hypervisor.framework · kern.hv_support: 1 GUEST · ONE MICROVM PER SANDBOX Linux 7.0.14 aarch64 its own kernel, Ubuntu 26.04.1 Docker Engine 29.8.1 its containers stay out of docker ps workspace mount virtiofs rw, same absolute path environment HTTPS_PROXY, keys proxy-managed docker-agent process the loop: model, tools, sub-agents filesystem, shell tools that run in the VM model call host.docker.internal:12434 nothing else in the guest
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. 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.
the command groups of sbxtextFull log
$ 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
…
Each group is cut to the commands this part names, and the other groups and the flags are cut.

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).

the command groups of docker-agenttextFull log
$ 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
…
Cut to the core group and four of the advanced commands. The diagnose group, the other commands, and the flags are cut.

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.

Fig. 1.2two ways to start docker-agent in a sandboxcomparison
Two ways to start docker-agent in a sandbox Two columns, one per launch path. Left: sbx run docker-agent on a project directory, where sbx creates the sandbox from docker/sandbox-templates:docker-agent, starts docker-agent run --yolo inside, reads only project config in the workspace, and applies the sbx policy; this manual has no capture of it. Right: docker-agent run --sandbox agent.yaml, where the host docker-agent drives sbx with docker/docker-agent-sbx-templates:latest, the binary inside reports version main, the agent file directory and the kit are mounted read-only, and models.dev and the sandbox allow hosts are opened; recorded in the capture. A · sbx run docker-agent B · docker-agent run --sandbox you type sbx run docker-agent ~/my-project sbx creates the sandbox docker/sandbox-templates:docker-agent startup command inside docker-agent run --yolo agent file project config in the workspace only network the sbx policy of the sandbox in this manual docs only, no capture you type docker-agent run --sandbox agent.yaml docker-agent drives sbx docker/docker-agent-sbx-templates:latest agent binary inside docker-agent version main agent file its directory mounted ro, kit ro network sbx policy, plus models.dev and allow hosts in this manual the recorded run
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. 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 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.

two agent binaries on the capture MactextFull log
$ 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]
Nothing is cut.

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.

Docker Sandboxes (sbx) and Docker Agent (docker-agent) sbx 0.47.0, docker-agent 1.149.0 · bf4169c · 2026-10-07 · Edition 2026.10