From docker sandbox and cagent to sbx and docker-agent

Two renames and one CLI restructure changed every command in the 2025 and early 2026 material, and this section maps each old line to its current form.

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 {{blog 2025-11-25}}. Desktop 4.58.0 replaced it with microVMs on 2026-01-26 {{docs-desktop 4.58.0}}, and Desktop 4.61.0 bundled plugin v0.12.0 on 2026-02-18 {{docs-desktop 4.61.0}}. 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 {{rel-sbx v0.21.0}}. Desktop 4.80.0 then ended the plugin on 2026-06-29:

label: the removal note
source: docs-desktop 4.80.0
---
Docker Desktop removed the experimental `docker sandbox` plugin. Move to `docker sbx`.

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 {{blog 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 {{docs-desktop 4.49.0}}. The agent docs say that Docker Desktop 4.49 to 4.62 called the feature cagent {{docs-agent Installation}}, and the docker agent plugin arrived with v1.23.3 on 2026-02-16 {{rel-agent v1.23.3}}.

Version 1.23.4 restructured the commands three days later, and v1.30.0 finished the rename on 2026-03-09 {{rel-agent v1.30.0}}. 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 {{docs-desktop 4.81.0}}. Desktop 4.94.0 bundles Docker Agent v1.144.0 {{docs-desktop 4.94.0}}, five releases behind the v1.149.0 binary this manual pins. Many Desktop notes state no bundled version at all (conflict C50).

Fig. 7.3two product tracks from 2025-09 to 2026-10timeline

Original SVG

Original source

id: fig-7-3
kind: timeline
title: two product tracks from 2025-09 to 2026-10
claim: Each old name survived its successor for months, and Docker Desktop removed the two of them one week apart, on 2026-06-29 and 2026-07-06.
caption: Read left to right on one date axis. Grey bars are the old names, blue and violet bars the current ones, and rose lines mark the three removals. The numbered key below names each event with its version. From research/sources/docs-desktop-release-notes.md, sbx-releases.md, and docker-agent-CHANGELOG.md.

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

title: the docker sandbox plugin, v0.12.0
source: research/sources/help-legacy-docker-sandbox.md
lang: text
note: The root help and the proxy flags, recorded on 2026-10-08 from the plugin that Desktop 4.61.0 bundled. The create, exec, and save sections are cut.
---
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

title: the docker agent plugin, v1.32.4
source: research/sources/help-legacy-docker-agent.md
lang: text
note: The root help and three run flags, recorded on 2026-10-08. The global flags already name the cagent directories.
---
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 {{help-agent docker-agent}}. 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_* {{rel-agent v1.30.0}}.

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

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]

title: docker sandbox on Docker Desktop 4.94.0
source: capture/out/29-docker-sandbox.txt
lang: text
note: docker sandbox version prints the same notice and is cut.
---
$ 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).

- Replace `docker sandbox` with `sbx` and `cagent` with `docker agent` before you follow any post from 2025 or early 2026.
- Check the date of a post against the version column before you type its command.
- Inspect `~/.docker/sandboxes/` after Desktop 4.80.0, and make a copy before you remove it, because nothing migrates it.
- Keep `~/.cagent` and `~/.config/cagent` where they are, because the rename left them alone.

Sources: docs-desktop 4.49.0, 4.58.0, 4.61.0, 4.64.0, 4.80.0, 4.81.0, 4.94.0 (research/sources/docs-desktop-release-notes.md); rel-agent v1.23.3, v1.23.4, v1.30.0, v1.147.0 (research/sources/docker-agent-CHANGELOG.md); rel-sbx v0.21.0, v0.31.0, v0.35.0, v0.42.0, v0.43.0, v0.45.0 (research/sources/sbx-releases.md); docs-agent Installation (research/sources/docs-docker-agent.md); help-sbx sbx create docker-agent (research/sources/help-sbx.md); help-agent docker-agent (research/sources/help-docker-agent.md); research/sources/help-legacy-docker-sandbox.md; research/sources/help-legacy-docker-agent.md; blog 2025-09-18, 2025-11-25, and research/conflicts-register.md rows C1, C17, C49, C50, C54, C107 to C112, S1 to S30; research/plan.md (the timeline); capture/out/01-help-sbx.txt, 01-help-docker-agent.txt, 02-daemon-status.txt, 04-env.txt, 04-second-sandbox.txt, 09-bypass-grep.txt, 29-docker-sandbox.txt, 29-docker-plugins.txt, 29-docker-agent-plugin.txt