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

Quick Start

Create a sandbox for the current project

CODEBLOCK0

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

CODEBLOCK1

Run an agent directly

CODEBLOCK2

Commands Reference

Lifecycle

CODEBLOCK3

Network Controls

The sandbox includes a network proxy for controlling outbound access.

CODEBLOCK4

Custom Templates

CODEBLOCK5

Workspace Mounting

The workspace path on the host is mounted into the sandbox via virtiofs. The mount path inside the sandbox preserves the host path structure:

Host OS	Host Path	Sandbox Path
Windows	INLINECODE2	INLINECODE3
macOS

/Users/me/projects/my-app | /Users/me/projects/my-app |
| Linux | /home/me/projects/my-app | /home/me/projects/my-app |

The agent's home directory is /home/agent/ with a symlinked workspace/ directory.

Environment Inside the Sandbox

Each sandbox VM includes:

• - Node.js (v20.x LTS)
• Git (latest)
• Python (system)
• curl, wget, standard Linux utilities
• npm (global install directory at /usr/local/share/npm-global/)
• Docker socket (at /run/docker.sock - Docker-in-Docker capable)

Proxy Configuration (auto-set)

CODEBLOCK6

Important: Node.js fetch (undici) does NOT respect HTTP_PROXY env vars by default. For npm packages that use fetch, create a require hook:

CODEBLOCK7

Run with: INLINECODE15

Patterns

Safe Package Exploration

CODEBLOCK8

Persistent Dev Environment

CODEBLOCK9

Locked-Down Agent Execution

CODEBLOCK10

Troubleshooting

"client version X is too old"

Update Docker Desktop to 4.49+. The sandbox plugin requires engine API v1.44+.

"fetch failed" inside sandbox

Node.js fetch doesn't use the proxy. Use the proxy-fix.js require hook above, or use curl instead: CODEBLOCK11

Path conversion on Windows (Git Bash / MSYS2)

Git Bash converts /path to C:/Program Files/Git/path. Prefix commands with: CODEBLOCK12

Sandbox won't start after Docker update

CODEBLOCK13