Docker Sandbox

Run agents and commands in isolated VM environments using Docker Desktop's sandbox feature. Each sandbox gets its own lightweight VM with filesystem isolation, network proxy controls, and workspace mounting via virtiofs.

When to Use

• Exploring untrusted packages or skills before installing them system-wide
• Running arbitrary code from external sources safely
• Testing destructive operations without risking the host
• Isolating agent workloads that need network access controls
• Setting up reproducible environments for experiments

Requirements

• Docker Desktop 4.49+ with the docker sandbox plugin
• Verify: docker sandbox version

Quick Start

Create a sandbox for the current project

docker sandbox create --name my-sandbox claude .

This creates a VM-isolated sandbox with:

• The current directory mounted via virtiofs
• Node.js, git, and standard dev tools pre-installed
• Network proxy with allowlist controls

Run commands inside

docker sandbox exec my-sandbox node --version
docker sandbox exec my-sandbox npm install -g some-package
docker sandbox exec -w /path/to/workspace my-sandbox bash -c "ls -la"

Run an agent directly

# Create and run in one step
docker sandbox run claude . -- -p "What files are in this project?"

# Run with agent arguments after --
docker sandbox run my-sandbox -- -p "Analyze this codebase"

Commands Reference

Lifecycle

# Create a sandbox (agents: claude, codex, copilot, gemini, kiro, cagent)
docker sandbox create --name <name> <agent> <workspace-path>

# Run an agent in sandbox (creates if needed)
docker sandbox run <agent> <workspace> [-- <agent-args>...]
docker sandbox run <existing-sandbox> [-- <agent-args>...]

# Execute a command
docker sandbox exec [options] <sandbox> <command> [args...]
  -e KEY=VAL          # Set environment variable
  -w /path            # Set working directory
  -d                  # Detach (background)
  -i                  # Interactive (keep stdin open)
  -t                  # Allocate pseudo-TTY

# Stop without removing
docker sandbox stop <sandbox>

# Remove (destroys VM)
docker sandbox rm <sandbox>

# List all sandboxes
docker sandbox ls

# Reset all sandboxes
docker sandbox reset

# Save snapshot as reusable template
docker sandbox save <sandbox>

Network Controls

The sandbox includes a network proxy for controlling outbound access.

# Allow specific domains
docker sandbox network proxy <sandbox> --allow-host example.com
docker sandbox network proxy <sandbox> --allow-host api.github.com

# Block specific domains
docker sandbox network proxy <sandbox> --block-host malicious.com

# Block IP ranges
docker sandbox network proxy <sandbox> --block-cidr 10.0.0.0/8

# Bypass proxy for specific hosts (direct connection)
docker sandbox network proxy <sandbox> --bypass-host localhost