sandbox-mcp

# sandbox-mcp [![CI](https://github.com/bird/sandbox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bird/sandbox-mcp/actions/workflows/ci.yml)

Local AI agent sandbox. Run isolated Linux VMs on your Mac in ~60ms. No cloud costs. VM-level isolation via Virtualization.framework. Works with MCP clients that support local stdio servers (Claude Code, Claude Desktop, Cursor).

## What this is

An MCP server that gives AI agents a sandboxed Linux environment using [Apple Containerization](https://github.com/apple/containerization) (Virtualization.framework). Each sandbox is a real VM — not a container sharing your kernel — that boots in ~700ms and executes commands in ~60ms via a persistent shell over vsock.

**Compared to cloud sandboxes (as of early 2025):**

| | Exec latency | Cost | Isolation |
|---|---|---|---|
| **This (local)** | ~60ms | Local hardware | VM (Virtualization.framework) |
| E2B | ~150ms + network | $0.18/hr | Firecracker microVM |
| Daytona | ~90ms + network | Usage-based | Docker container |

## Quick demo

Once registered, your MCP client can use the sandbox tools directly:

```
Agent: exec(command="uname -a")
→ Linux mcp-sb-abc123 6.12.6 #1 SMP aarch64 Linux

Agent: install(packages="python3 py3-pip")
→ Installed python3 py3-pip (1230ms)

Agent: exec(command="python3 -c 'print(sum(range(1000)))'")
→ 499500

Agent: bg(command="python3 -m http.server 8000")
→ Started [bg-a1b2c3] PID 42

Agent: expose(port=8000)
→ Forwarding localhost:8000 → 'default':8000
  Open http://localhost:8000
```

Cold boot is ~700ms, subsequent commands ~60ms each.

## Requirements

- Apple Silicon Mac (M1+)
- macOS 15 Sequoia+
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (for packaging)

## Setup

### 1. Install Apple Containers

```bash
# Download and install the container CLI
curl -LO https://github.com/apple/containerization/releases/download/v0.9.0/container-v0.9.0.pkg
sudo installer -pkg container-v0.9.0.pkg -target /

# Start the container system (dow