Sandbox

You run code inside isolated Docker containers through an MCP server that exposes a sandboxed environment for writing, running, and testing code across languages. It lets you create containers from Docker images, install packages, and manage development environments without affecting your host system.

How to use

Connect to the Sandbox MCP Server using your MCP client to create and manage isolated containers. You can spin up a Python container to write and test code, run programs in other languages, install packages, and persist or export environments for reuse. All code executes inside containers that are isolated from your host, with separate file systems and restricted host access.

How to install

Prerequisites: you need Python 3.9 or higher and Docker installed and running on your machine. You also use the uv package manager to manage the MCP server locally.

How to install

# Prerequisites
python3 --version
docker --version

# Install your MCP runner (uv) and set up a local environment for the Sandbox MCP Server
# Step 1: Ensure uv is available and create a virtual environment
# Install uv if not already installed (example for macOS/Linux)
pip install uv

# Step 2: Clone the sandbox server project and enter the directory
git clone <your-repo-url>
cd sandbox_server

# Step 3: Create and activate a virtual environment with uv
uv venv
source .venv/bin/activate  # On Unix/MacOS
# Or on Windows:
# .venv\Scripts\activate

# Step 4: Install dependencies for the Sandbox MCP Server
uv pip install .

Configuration and integration

To connect Claude Desktop or a similar MCP client to the Sandbox MCP Server, configure the MCP server entry with the following details. This runs the server in a local stdio mode using uv and points to the sandbox server script.

Configuration and integration

{
  "mcpServers": {
    "sandbox": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sandbox_server",
        "run",
        "sandbox_server.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/sandbox_server"
      }
    }
  }
}

Security and notes

All code executes in isolated Docker containers. Containers are automatically removed after use and file systems are isolated between containers. The host system access is restricted to protect your environment.

Project structure and tools

You typically have a sandbox_server directory containing the main server implementation, project configuration, and supporting docs. The server offers a set of tools to manage containers, files, and commands within those containers.

Usage examples and workflow

Create and run a Python container to test code, then save or export the environment as needed. You can persist containers so they stay running after the client closes, or convert your setup into a Docker image or a Dockerfile for reproducible environments.

Mutable environment management

You can save the current container state as a Docker image and export a Dockerfile to recreate the environment elsewhere. This supports sharing environments or deploying them to other systems.

Notes on usage patterns

The server supports creating containers with various Docker images, installing packages, and running commands in isolated containers. You can manage the lifecycle of containers, including stopping, starting, and removing them as needed.

Available tools

The server provides: create_container_environment, create_file_in_container, execute_command_in_container, save_container_state, export_dockerfile, exit_container.

Available tools

create_container_environment

Creates a new Docker container with the specified image and environment setup.

create_file_in_container

Creates or writes a file inside a running container.

execute_command_in_container

Executes a command inside a running container and captures output.

save_container_state

Saves the current container state to a persistent image for reuse.

export_dockerfile

Exports a Dockerfile that reproduces the current container environment.

exit_container

Closes and cleans up the active container session.