From docker sandbox and cagent to sbx and docker-agent

A blog post from 2026-02-23 tells you to run docker sandbox run claude and to point the proxy at host.docker.internal:3128. A talk from 2025-09-24 shows cagent run agent.yaml and cagent push. On a machine with Docker Desktop 4.94.0, sbx 0.47.0, and docker-agent 1.149.0, neither command exists. When you finish this section, you can map any command from that material to its current form and name the version that changed it.

Two tracks and three removals

The sandbox product had four lives. The plan's timeline dates a container-based docker sandbox run to Docker Desktop 4.50.0 on 2025-11-06, and the preview blog followed on 2025-11-25. Desktop 4.58.0 replaced it with microVMs on 2026-01-26, and Desktop 4.61.0 bundled plugin v0.12.0 on 2026-02-18. That plugin is the one whose help this section quotes. The standalone sbx binary had its first public tag, v0.21.0, on 2026-03-31. Desktop 4.80.0 then ended the plugin on 2026-06-29:

No docker sbx command exists in any help tree, and the binary is sbx (conflict C1).

The agent product had three names. It launched as cagent with a blog on 2025-09-18, and Desktop 4.49.0 bundled it on 2025-10-23. The Desktop notes for 4.49.0 now use the current name, Docker Agent. The agent docs say that Docker Desktop 4.49 to 4.62 called the feature cagent, and the docker agent plugin arrived with v1.23.3 on 2026-02-16.

Version 1.23.4 restructured the commands three days later, and v1.30.0 finished the rename on 2026-03-09. The docs date Docker Agent in Desktop to 4.63, while the first release note that names it is 4.64.0 with v1.27.1 (conflict C49). Desktop 4.81.0 removed the deprecated cagent binary on 2026-07-06. Desktop 4.94.0 bundles Docker Agent v1.144.0, five releases behind the v1.149.0 binary this manual pins. Many Desktop notes state no bundled version at all (conflict C50).

The old command trees

Management Commands:
  create      Create a sandbox for an agent
  network     Manage sandbox networking

Commands:
  exec        Execute a command inside a sandbox
  ls          List VMs
  reset       Reset all VM sandboxes and clean up state
  rm          Remove one or more sandboxes
  run         Run an agent in a sandbox
  save        Save a snapshot of the sandbox as a template
  stop        Stop one or more sandboxes without removing them
  version     Show sandbox version information
…
      --bypass-cidr string   Bypass MITM proxy for an IP range in CIDR
                             notation (can be specified multiple times)
      --bypass-host string   Bypass MITM proxy for a domain or IP (can be
                             specified multiple times)
…
      --policy allow|deny    Set the default policy

Core Commands:
  new         Create a new agent configuration
  run         Run an agent
  share       Share agents

Advanced Commands:
  alias       Manage aliases
  eval        Run evaluations for an agent
  serve       Start an agent as a server
…
      --sandbox                   Run the agent inside a Docker sandbox (requires Docker Desktop with sandbox support)
…
      --template string           Template image for the sandbox (passed to docker sandbox create -t)
…
      --yolo                      Automatically approve all tool calls without prompting

Beside them, the v0.47.0 tree in the captured sbx help groups policy, secret, template, and mcp under Management Commands, and network and save are gone. The v1.149.0 tree in the captured docker-agent help adds setup, doctor, models, toolsets, sessions, debug, sandbox, and serve chat, which Part 5 covers.

The command map

The rows restate the register's stale-advice list S1 to S30 and the plugin rows C107 to C112, which the sources section prints in full.

What kept the old name

The rename did not touch the directories. docker-agent --help still defaults --data-dir to ~/.cagent, --config-dir to ~/.config/cagent, and --cache-dir to ~/Library/Caches/cagent. The v1.32.4 plugin printed the same three values, and the debug log stays at ~/.cagent/cagent.debug.log (conflict C54). The CAGENT_* variables are still read next to DOCKER_AGENT_*.

The OCI annotation became io.docker.agent.version with the old name kept. The Hub image moved from docker/cagent to docker/docker-agent, and the image keeps cagent as a symlink. In sbx, cagent remains an alias of the docker-agent create subcommand.

Sandbox state did not migrate. The plugin kept VM state under ~/.docker/sandboxes/vm/ and an image cache under ~/.docker/sandboxes/image-cache/, as its own reset help says. sbx keeps its socket and log under ~/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/ (the capture), and no page describes a migration (conflict C17). No capture lists the leftover directories.

On Desktop 4.94.0, docker info still lists the plugin as sandbox v0.13.0 (29-docker-plugins.txt), and each of its commands prints the removal notice:

$ docker sandbox --help
"docker sandbox" is deprecated and has been removed.

Please migrate to Docker Sandboxes: https://www.docker.com/products/docker-sandboxes
[exit 1]

The notice names the product page, not the docker sbx of the 4.80.0 note. On the same host, the bundled docker agent version prints v1.144.0 and the Homebrew docker-agent version prints v1.149.0 (29-docker-agent-plugin.txt).