docker-sandbox

# 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

```bash
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

```bash
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

```bash
# 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

```bash
# 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...