Docker Sandboxes Tutorial and Cheatsheet

AI coding agents have become incredibly powerful. Tools like Claude Code, GitHub Copilot, and Devin AI can write code, debug issues, and even manage entire development workflows. But there's a critical problem: running them locally introduces significant risks.

The Three Horsemen of AI Agent Risks

Environment Pollution

AI agents can install packages and dependencies globally, creating conflicts with other projects. Imagine your agent installing a different version of Python or Node.js that breaks your existing applications.

# Agent installs globally
npm install -g some-package@beta

# Now your other projects using stable versions are broken

Unintended File System Changes

An agent could mistakenly modify, move, or delete critical files outside the project workspace. One wrong command and your ~/.ssh keys, environment configs, or system files could be compromised.

Recent research from NVIDIA's AI Red Team (CVE-2024-12366) demonstrated how AI-generated code can escalate into remote code execution (RCE) when executed without proper isolation.

Security Vulnerabilities

Giving an agent unrestricted network and file access could expose sensitive data or create security holes. According to a comprehensive survey by ACM Computing Surveys, insufficient isolation between agents and the host system poses one of the most significant security challenges in agentic AI systems.

The uncomfortable truth: Most LLM tools have full access to your machine by default, with only imperfect attempts at blocking risky behavior.

The Solution: Isolated Yet Familiar

Docker Sandboxes solves these problems by isolating AI agents from your local machine while preserving a familiar development experience

Three Core Principles

🛡️ Security & Isolation

Protect your host machine from unintended changes, dependency conflicts, and vulnerabilities. The agent runs in a containerized environment with controlled access.

🎯 High-Fidelity Dev Experience

Your project directory is mounted at the same absolute path inside the container. File paths in error messages match your host, scripts with hard-coded paths work as expected, and changes are reflected instantly.

# On your Mac/Linux host
/Users/alice/projects/myapp

# Inside the sandbox
/Users/alice/projects/myapp  # Exact same path!

⚙️ Powerful & Customizable

Tailor the environment with variables, Docker socket access (with caution), volume mounts, and custom templates for any workflow.

Getting Started in 60 Seconds

Prerequisites

• Docker Desktop 4.50 or later (Download)
• A Claude Code subscription (or other supported AI agent)

Run Your First Sandboxed Agent

# Navigate to your project
cd ~/my-project

# Start the sandbox
docker sandbox run claude

That's it! On first run, you'll be prompted to authenticate. Credentials are securely stored in a persistent Docker volume for future sessions.

What Just Happened?

The docker sandbox run command automated several key steps:

1. Container Creation: Created from docker/sandbox-templates:claude-code
2. Workspace Mounting: Your current directory mounted at the exact same path
3. Git Configuration: Your host's Git user.name and user.email injected automatically
4. Persistent Credentials: API key stored in docker-claude-sandbox-data volume

Under the Hood: How It Works

The Anatomy of a Sandbox

┌─────────────────────────────────────────┐
│         Host Machine (Protected)         │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │   Sandbox Container (Isolated)     │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐ │ │
│  │  │   AI Agent (Claude Code)     │ │ │
│  │  └──────────────────────────────┘ │ │
│  │            ↕ Mounted                │ │
│  │  ┌──────────────────────────────┐ │ │
│  │  │   Project Workspace          │←┼─┼─┐
│  │  │   /Users/dev/project         │ │ │ │
│  │  └──────────────────────────────┘ │ │ │
│  └────────────────────────────────────┘ │ │
│                                          │ │
│  ┌────────────────────────────────────┐ │ │
│  │   Your Actual Project Files        │ │ │
│  │   /Users/dev/project               │◄┘ │
│  └────────────────────────────────────┘   │
└─────────────────────────────────────────┘

One Sandbox Per Workspace

Docker enforces one sandbox per workspace. Running docker sandbox run again in the same directory reuses the existing container. This means:

• Installed packages persist across sessions
• Environment changes are maintained
• Temporary files remain between runs

Important: To modify a sandbox's configuration, you must remove and recreate it.

Advanced Configuration

Managing Your Sandboxes

# List all running sandboxes
docker sandbox ls

# Inspect a sandbox's configuration (JSON output)
docker sandbox inspect <sandbox-id>

# Remove a specific sandbox
docker sandbox rm <sandbox-id>

# Pro Tip: Remove all sandboxes at once
docker sandbox rm $(docker sandbox ls -q)

Environment Variables

Use the -e flag to pass environment variables directly into the sandbox.

Example: Full Development Environment Setup

docker sandbox run \
  -e NODE_ENV=development \
  -e DATABASE_URL=postgresql://localhost/myapp_dev \
  -e DEBUG=true \
  claude

Example: API Keys for Testing

docker sandbox run -e STRIPE_TEST_KEY=sk_test_xxx claude

⚠️ Caution: Only use test or development API keys in sandboxes. Never expose production keys.

Volume Mounts

Use the -v flag to mount host directories into the sandbox. Syntax: host-path:container-path[:ro]

Example: Machine Learning Workflow

docker sandbox run \
  -v ~/datasets:/data:ro \
  -v ~/models:/models \
  -v ~/.cache/pip:/root/.cache/pip \
  claude

This provides:

• Read-only access to datasets (prevents accidental modifications)
• Read-write access to save trained models
• Persistent pip cache for faster package installs

Custom Templates

Instead of installing tools every time, build a custom Docker image with everything pre-installed.

Step 1: Create a Dockerfile

# syntax=docker/dockerfile:1
FROM docker/sandbox-templates:claude-code

# Install the 'ruff' linter using 'uv'
RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
    . ~/.local/bin/env && \
    uv tool install ruff@latest

Step 2: Build and Run

# Build your custom template image
docker build -t my-python-env .

# Run the agent using your new template
docker sandbox run --template my-python-env claude

Security Considerations

Docker Socket Access (Use With Extreme Caution)

The --mount-docker-socket flag gives the agent full access to your Docker daemon.

docker sandbox run --mount-docker-socket claude

⚠️ SECURITY WARNING

Mounting the Docker socket grants the agent root-level privileges on your system.

• Can start/stop any container
• Access volumes and networks
• Potentially escape the sandbox

Only use this option when you fully trust the code the agent is working with.

When It's Useful

• Building images from a Dockerfile
• Running multi-container applications with Docker Compose
• Testing and validating containerized applications

Authentication Strategies

--credentials=sandbox (Default)

Securely stores your API key in a managed Docker volume for reuse across sandboxes.

docker sandbox run claude  # Uses sandbox mode by default

--credentials=none

No automatic credential management. You must authenticate manually inside the container for each new sandbox.

docker sandbox run --credentials=none claude

Best Practices

Based on research from Martin Fowler's team and NVIDIA's AI security guidelines:

1. Least Privilege: Start with read-only access for AI agents
2. Never store production credentials in files accessible to agents
3. Use temporary tokens with limited scopes
4. Review all AI-generated code before committing
5. Limit Docker socket access to trusted workflows only
6. Monitor resource usage to detect anomalies

Real-World Use Cases

1. Machine Learning Development

docker sandbox run \
  -v ~/datasets:/data:ro \
  -v ~/models:/models \
  -v ~/.cache/pip:/root/.cache/pip \
  claude

Scenario: Train a model on the MNIST dataset

• Agent: "Train a model on the MNIST dataset and save it to /models"
• Claude: *runs* python train.py --data /data/mnist --output /models/mnist_model.h5

2. Multi-Container Application Development

docker sandbox run --mount-docker-socket claude

Scenario: Build and test a microservices application

• Agent can build Docker images
• Run Docker Compose setups
• Test containerized applications

3. Frontend Development with Hot Reload

docker sandbox run \
  -e NODE_ENV=development \
  -v ~/.cache/go-build:/root/.cache/go-build \
  claude

4. Continue Previous Work

# Continue the last conversation
docker sandbox run claude --continue

5. Start with a Specific Task

docker sandbox run claude "Add error handling to the login function"

Troubleshooting

Common Issues and Solutions

When to Recreate a Sandbox

You must remove and recreate a sandbox when changing:

• Environment variables (-e)
• Volume mounts (-v)
• Docker socket access (--mount-docker-socket)
• Credentials mode (--credentials)

# Get the sandbox ID
docker sandbox ls

# Remove it
docker sandbox rm <sandbox-id>

# Recreate with new configuration
docker sandbox run -e NEW_VAR=value claude

The Future of AI Agent Security

Docker Sandboxes represents a critical step forward in making AI agents both powerful and safe. As recent vulnerabilities in tools like OpenAI Codex CLI (CVE-2025-61260) demonstrate, the security of AI coding assistants is an evolving challenge.

Industry Trends

1. Containerization as Standard: Leading platforms are adopting container-based isolation (E2B Sandboxes, Daytona SDK)
2. MCP Integration: Model Context Protocol enables secure, controlled access to external tools
3. Zero Trust Architecture: Assuming all AI-generated code is untrusted by default
4. Ephemeral Runtimes: Destroying execution environments after each task

What's Next?

Docker is actively developing:

• Enhanced sandbox templates for different tech stacks
• Better integration with CI/CD pipelines
• Advanced security policies and guardrails
• Cross-platform support improvements

Conclusion

Docker Sandboxes solves the fundamental tension between AI agent autonomy and system security. By providing true isolation with zero-overhead development experience, it enables developers to harness the full power of AI coding assistants without compromising their machines.

The three principles that make it work:

1. Security through isolation - Containers protect your host
2. Familiarity through path mounting - Same paths, same workflows
3. Power through customization - Adapt to any use case

As AI agents become more sophisticated and autonomous, proper sandboxing isn't optional—it's essential. Docker Sandboxes makes it practical.

References

1. Docker Sandboxes Official Documentation
2. How Code Execution Drives Key Risks in Agentic AI Systems - NVIDIA
3. AI Agents Under Threat: A Survey - ACM Computing Surveys
4. Agentic AI and Security - Martin Fowler
5. Security of AI Agents - arXiv
6. The Hidden Security Risks of SWE Agents - Pillar Security