Code Sandbox MCP

A remote Model Context Protocol server that gives AI clients a persistent Linux sandbox. The model runs any bash command as root in a Docker container with internet access, installs whatever it needs, and hands files back to the user through download links.

There is deliberately no command filtering. Isolation comes from the container: it is not privileged, has no Docker socket and no host directories mounted, and has memory and CPU limits.

It started as a fork of philschmid/code-sandbox-mcp and now uses a different design: one long-lived container instead of a container per snippet, and streamable HTTP with OAuth instead of stdio.

Tools

• execute(command, timeout=3600): run a bash command in /sandbox. Returns stdout, stderr and the exit code. Output above MAX_OUTPUT_BYTES per stream is truncated in the middle.

• share_file(path): return a signed, expiring public download link for a file in the sandbox. Use it for PDFs, images, audio, video or anything else that cannot be returned as text.

Related MCP server: Persistent VPS Compute MCP

Behavior

• /sandbox lives on a named Docker volume. A top-level entry with no change inside it for FILE_TTL seconds (default 168 hours) is deleted by an hourly cleanup.

• Packages installed with pip, npm or apt-get persist in the container. A stopped container is restarted, not recreated.

• Each call is a fresh bash process: cd and exported variables do not carry over.

• Long-running processes can be detached with setsid nohup <cmd> > log 2>&1 &.

Authentication

The server is its own OAuth 2.1 authorization server with dynamic client registration, so MCP clients such as Claude connect with only the URL https://<your-host>/mcp. When a client connects, the user is sent to a sign-in page that asks for SANDBOX_API_KEY. Registered clients and tokens are kept in oauth-state.json so restarts do not force a new sign-in.

Download links from share_file are signed with the same key and valid for LINK_TTL seconds. Rotating the key invalidates them.

Setup

Requires Docker and Python 3.10+.

docker build -f containers/Dockerfile.unified -t code-sandbox:latest .
python3 -m venv .venv
.venv/bin/pip install fastmcp docker uvicorn

Create .env (keep it private, chmod 600 .env):

SANDBOX_API_KEY=<random string, e.g. python3 -c "import secrets;print(secrets.token_urlsafe(32))">
SANDBOX_PUBLIC_URL=https://sandbox.example.com
SANDBOX_HOST=127.0.0.1
SANDBOX_PORT=8891

Run it, for example as a systemd service:

[Unit]
Description=Code Sandbox MCP Server
After=network-online.target docker.service
Requires=docker.service

[Service]
WorkingDirectory=/path/to/code-sandbox-mcp
EnvironmentFile=/path/to/code-sandbox-mcp/.env
ExecStart=/path/to/code-sandbox-mcp/.venv/bin/python sandbox_server.py
Restart=always

[Install]
WantedBy=multi-user.target

Put it behind HTTPS at SANDBOX_PUBLIC_URL (a reverse proxy or a Cloudflare Tunnel). Commands can run longer than a proxy's idle timeout because the MCP response stream sends keep-alive pings.

Settings

The image

containers/Dockerfile.unified is based on python:3.13-slim and adds Node.js 22 with npm, pnpm, yarn, bun, TypeScript and tsx; uv; a broad set of Python data, document and web libraries; Playwright with headless Chromium; and ffmpeg, ImageMagick, pandoc, poppler, build tools and CJK fonts. Edit it to change what is preinstalled.

Legacy code

src/, examples/, tests/, .gemini/, containers/Dockerfile.python and containers/Dockerfile.nodejs belong to the original stdio server and are not used by sandbox_server.py.

License

MIT, see license.