Share feedback
Answers are generated based on the documentation.

Using sandboxes effectively

Table of contents
Availability: Experimental
Requires: Docker Desktop 4.58 or later

This guide covers practical patterns for working with sandboxed agents.

Basic workflow

Create a sandbox for your project:

$ cd ~/my-project
$ docker sandbox run claude .

The sandbox persists. Stop and restart it without losing installed packages or configuration:

$ docker sandbox run <sandbox-name>  # Reconnect later

Installing dependencies

Ask the agent to install what's needed:

You: "Install pytest and black"
Claude: [Installs packages via pip]

You: "Install build-essential"
Claude: [Installs via apt]

The agent has sudo access. Installed packages persist for the sandbox lifetime. This works for system packages, language packages, and development tools.

For teams or repeated setups, use Custom templates to pre-install tools.

Docker inside sandboxes

Agents can build images, run containers, and use Docker Compose. Everything runs inside the sandbox's private Docker daemon.

Testing containerized apps

You: "Build the Docker image and run the tests"

Claude: *runs*
  docker build -t myapp:test .
  docker run myapp:test npm test

Containers started by the agent run inside the sandbox, not on your host. They don't appear in your host's docker ps.

Multi-container stacks

You: "Start the application with docker-compose and run integration tests"

Claude: *runs*
  docker-compose up -d
  docker-compose exec api pytest tests/integration
  docker-compose down

Remove the sandbox, and all images, containers, and volumes are deleted.

What persists

While a sandbox exists:

  • Installed packages (apt, pip, npm, etc.)
  • Docker images and containers inside the sandbox
  • Configuration changes
  • Command history

When you remove a sandbox:

  • Everything inside is deleted
  • Your workspace files remain on your host (synced back)

To preserve a configured environment, create a Custom template.

Named sandboxes

Use meaningful names for sandboxes you'll reuse:

$ docker sandbox run --name myproject claude ~/project

Create multiple sandboxes for the same workspace:

$ docker sandbox create --name dev claude ~/project
$ docker sandbox create --name staging claude ~/project
$ docker sandbox run dev

Each maintains separate packages, Docker images, and state, but share the workspace files.

Debugging

Access the sandbox directly with an interactive shell:

$ docker sandbox exec -it <sandbox-name> bash

Inside the shell, you can inspect the environment, manually install packages, or check Docker containers:

agent@sandbox:~$ docker ps
agent@sandbox:~$ docker images

List all sandboxes:

$ docker sandbox ls

Managing multiple projects

Create sandboxes for different projects:

$ docker sandbox create claude ~/project-a
$ docker sandbox create claude ~/project-b
$ docker sandbox create claude ~/work/client-project

Each sandbox is completely isolated. Switch between them by running the appropriate sandbox name.

Remove unused sandboxes to reclaim disk space:

$ docker sandbox rm <sandbox-name>

Next steps