# sandbox-mcp

MCP service that exposes sandboxed code execution tools. Delegates execution to a
`sandbox-runner` VM running Firecracker microVMs on Proxmox (nested KVM).

## Tools

| Tool | Description |
|------|-------------|
| `shell_run` | Run bash script in isolated microVM |
| `python_run` | Run Python 3 code in isolated microVM |
| `node_run` | Run Node.js code in isolated microVM |

All tools: no network access, 256MB RAM, 0.5 CPU, configurable timeout (default 15s).

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SANDBOX_MCP_INTERNAL_TOKEN` | Yes | Auth token for MCP clients |
| `SANDBOX_RUNNER_URL` | No | URL of sandbox-runner VM (e.g. `http://sandbox-runner:8080`) |
| `SANDBOX_RUNNER_TOKEN` | No | Bearer token for sandbox-runner auth |
| `PORT` | No | HTTP port (default `3001`) |
| `SANDBOX_TIMEOUT_MS` | No | Default execution timeout ms (default `15000`) |

## Sandbox Runner Contract

The service expects a `sandbox-runner` HTTP API (deployed separately on Proxmox):

```
POST /run
  Body: { lang: "bash" | "python" | "node", code: string, timeoutMs: number }
  Response: { stdout: string, stderr: string, exitCode: number, durationMs: number }

GET /health
  Response: { status: "ok", poolSize: number, available: number }
```

## Without Proxmox (pre-deployment)

If `SANDBOX_RUNNER_URL` is not set, the service starts normally but all tool calls
return a `503 not configured` message. The feature flag `sandbox_exec` should remain
disabled until the runner is deployed.

## Endpoints

- `GET /health` — health check, includes `runnerConfigured` boolean
- `POST /mcp` — MCP JSON-RPC (StreamableHTTP)
- `GET /mcp` — MCP SSE transport