Migrating from legacy sandboxes - Docker

The most recent versions of Docker Desktop create microVM-based sandboxes, replacing the container-based implementation released in earlier versions. 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 or later:

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.

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

Remove the old sandbox containers:

console

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

Remove the credential volume:

console

$ docker volume rm docker-claude-sandbox-data

Create a new microVM sandbox:

console

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

Reinstall dependencies. Ask the agent to install needed tools:

plaintext

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.

Inspect your old sandbox to see what's installed:
console
```
$ docker exec <old-sandbox-container> dpkg -l
```

Create a custom template with your tools:

dockerfile

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

Build your template:

console

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

Create a new sandbox with your template:
console
```
$ docker sandbox create --template my-sandbox-template:v1 claude ~/project
```
[!NOTE] The --pull-template flag was introduced in Docker Desktop 4.61 (Sandbox version 0.12). On Docker Desktop 4.58–4.60, use --load-local-template to use a locally-built template image.
Run the sandbox:
console
```
$ 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:

console

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

Remove all stopped containers and unused volumes:

console

$ 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:

console

$ docker sandbox run ~/project

New command structure:

console

$ docker sandbox run claude ~/project

The agent name is now a required parameter when creating sandboxes, and you run the sandbox by name.