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