sandbox

Sandbox MCP is a secure execution environment that lets LLMs (MCP hosts/clients) run code inside isolated Docker sandboxes. It provides a simple, AI-native server that can be integrated into your existing MCP setup so you can test, validate, and execute code safely without risking your host system. The server exposes a straightforward interface where each request can be processed through predefined sandboxes (e.g., Python, Rust, Go, JavaScript, network tools, and more) depending on your configuration. This enables use cases like secure code execution, automated testing of generated snippets, user-submitted code validation, and network diagnostics within contained environments. The README highlights a variety of sandboxes you can leverage, such as shell commands, Python, Rust, network-tools, Go, JavaScript, APISIX, and Java, each designed to run code or commands in isolation with optional network access as configured by the sandbox itself. To use it, run the sandbox-mcp binary and point your MCP host or client (for example Claude Desktop or Cursor IDE) to the sandbox-mcp executable, passing the appropriate --stdio flag as shown in the configuration example. Once connected, you can initialize the server’s configuration, pull or build sandboxes, and reference the sandbox-mcp path in your client’s mcp.json or claude_desktop_config.json.

Prerequisites:

• Go 1.24 or higher (for building from source) or download the prebuilt binary from the Releases page.
• Docker (for building and running sandboxes locally).

Install from binaries (recommended):

1. Visit the Releases page at https://github.com/pottekkat/sandbox-mcp/releases and download the appropriate binary for your OS (for example sandbox-mcp_Darwin_arm64.tar.gz).
2. Extract and place the sandbox-mcp binary in a directory included in your PATH.
3. Verify installation:
   • which sandbox-mcp
   • sandbox-mcp --help

Install from source (Go):

1. Ensure Go is installed (Go 1.24+).
2. Build the project: go install github.com/pottekkat/sandbox-mcp/cmd/sandbox-mcp@latest
3. Verify binary location: which sandbox-mcp
4. Run an initial pull/build as described in the README to fetch default sandboxes: sandbox-mcp --pull sandbox-mcp --build

Configuration:

• After installing, configure MCP clients to point to the local sandbox-mcp executable, for example in mcp.json: { "mcpServers": { "sandbox-mcp": { "command": "/path/to/sandbox-mcp", "args": ["--stdio"] } } }

Notes:

• Ensure Docker is running if you intend to build or run sandboxes that require container execution.
• Rebuild or pull sandboxes with the provided commands when updating from the repository.

Tips and common issues:

• If the sandbox-mcp binary is not found, ensure the path in your mcp.json points to the correct executable and that it has execute permissions.
• When pulling sandboxes, confirm network access and Docker daemon availability; some sandboxes may require network tools or restricted network access.
• For Claude Desktop integration, replace path placeholders with the actual path to the sandbox-mcp binary and ensure your JSON configuration uses --stdio for real-time bidirectional I/O.
• If sandboxes fail to start, check Docker daemon logs and ensure your user account has permission to run Docker commands.
• You can add additional environment variables in the mcp_config under env to tailor sandbox behavior (e.g., SANDBOX_CONFIG_URL, API_KEYS, or other secrets) as placeholders before moving to production.