Migrating from legacy sandboxes

Docker Desktop 4.58 introduces microVM-based sandboxes, replacing the previous container-based implementation. This guide helps you migrate from legacy sandboxes to the new architecture.

What changed

Docker Sandboxes now run in lightweight microVMs instead of containers. Each sandbox has a private Docker daemon, better isolation, and network filtering policies.

Note

If you need to use legacy container-based sandboxes, install Docker Desktop 4.57.

After upgrading to Docker Desktop 4.58:

• Old sandboxes don't appear in docker sandbox ls
• They still exist as regular Docker containers and volumes
• You can see them with docker ps -a and docker volume ls
• Old sandboxes won't work with the new CLI commands
• Running docker sandbox run creates a new microVM-based sandbox

Migration options

Choose the approach that fits your situation:

Option 1: Start fresh (recommended)

This is the simplest approach for experimental features. You'll recreate your sandbox with the new architecture.

1. Note any important configuration or installed packages in your old sandbox.

2. Remove the old sandbox containers:

   $ docker rm -f $(docker ps -q -a --filter="label=docker/sandbox=true")
   

3. Remove the credential volume:

   $ docker volume rm docker-claude-sandbox-data
   

4. Create a new microVM sandbox:

   $ docker sandbox create claude ~/project
   $ docker sandbox run <sandbox-name>
   

5. Reinstall dependencies. Ask the agent to install needed tools:

   You: "Install all the tools needed to build and test this project"
   Claude: [Installs tools]

What you lose:

• API keys (re-authenticate on first run, or set ANTHROPIC_API_KEY)
• Installed packages (reinstall via the agent)
• Custom configuration (reconfigure as needed)

What you gain:

• Better isolation (microVM versus container)
• Private Docker daemon for test containers
• Network filtering policies
• Improved security

Option 2: Migrate configuration

If you have extensive customization, preserve your setup by creating a custom template.

1. Inspect your old sandbox to see what's installed:

   $ docker exec <old-sandbox-container> dpkg -l
   

2. Create a custom template with your tools:

   FROM docker/sandbox-templates:claude-code
   
   USER root
   
   # Install your tools
   RUN apt-get update && apt-get install -y \
       build-essential \
       nodejs \
       npm
   
   # Install language-specific packages
   RUN npm install -g typescript eslint
   
   # Add any custom configuration
   ENV EDITOR=vim
   
   USER agent

3. Build your template:

   $ docker build -t my-sandbox-template:v1 .
   

4. Create a new sandbox with your template:

   $ docker sandbox create --template my-sandbox-template:v1 \
       --load-local-template \
       claude ~/project
   

5. Run the sandbox:

   $ docker sandbox run <sandbox-name>
   

If you want to share this template with your team, push it to a registry. See Custom templates for details.

Cleanup old resources

After migrating, clean up legacy containers and volumes:

Remove specific sandbox:

$ docker rm -f <old-sandbox-container>
$ docker volume rm docker-claude-sandbox-data

Remove all stopped containers and unused volumes:

$ docker container prune
$ docker volume prune

Warning

docker volume prune removes ALL unused volumes, not just sandbox volumes. Make sure you don't have other important unused volumes before running this command.

Understanding the differences

Architecture

Old (container-based):

• Sandboxes were Docker containers
• Appeared in docker ps
• Mounted host Docker socket for container access
• Stored credentials in Docker volume

New (microVM-based):

• Sandboxes are lightweight microVMs
• Use docker sandbox ls to see them
• Private Docker daemon inside VM
• Credentials via ANTHROPIC_API_KEY environment variable or interactive auth

CLI changes

Old command structure:

$ docker sandbox run ~/project

New command structure:

$ docker sandbox run claude ~/project

The agent name (claude, codex, gemini, cagent, kiro) is now a required parameter when creating sandboxes, and you run the sandbox by name.