zacjansen/inkersion-sandbox-mcp

🔒 Multi-Language Code Execution Sandbox MCP Server

A Model Context Protocol (MCP) server that provides secure, isolated code execution across multiple programming languages using Docker containers. Perfect for AI agents that need to test and validate code before presenting it to users.

🌟 Features

• 🌐 Multi-Language Support: Python, JavaScript/Node.js, Bash, Go, Rust, Java, Ruby, PHP, and more
• 🗃️ Persistent Sessions: Manage long-lived sandboxes with file I/O and package installation
• 🔒 Secure Isolation: Each execution runs in a disposable Docker container
• 📦 Dependency Management: Automatically install packages before execution or mid-session
• 🚫 Network Isolation: Containers have no network access by default
• ⚡ Fast: Reuses Docker images for quick startup
• 🎯 MCP Native: Built on the Model Context Protocol for seamless agent integration
• 📊 Rich Output: Captures stdout, stderr, exit codes, and execution time

🎯 Use Case

This sandbox is designed for the following workflow:

1. Agent creates script in any supported language
2. Before proposing to user, agent calls the sandbox MCP to:
   • Install dependencies (if needed)
   • Run the code in an isolated environment
   • Get logs and outputs
3. Agent provides a now-validated and tested script to the user

📋 Supported Languages

🚀 Quick Start

Two Deployment Options

Option A: Local Installation

Run the sandbox on your own machine (requires Docker Desktop)

Option B: Railway Cloud Deployment

Deploy to Railway - users connect via WebSocket (no local Docker needed)

See for cloud deployment guide.

Prerequisites (Local Installation)

• Docker installed and running
• Python 3.8+ installed
• pip package manager

Installation

1. Clone or download this repository:

git clone <your-repo-url>
cd code-execution-sandbox

2. Create a virtual environment (recommended):

python -m venv .venv

# On Windows:
.venv\Scripts\activate

# On macOS/Linux:
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Verify Docker is running:

docker ps

Running the MCP Server

Standalone Mode (for testing)

python main.py

With MCP Clients (Cursor, Claude Desktop, etc.)

The server communicates via stdio and is designed to be launched by MCP clients.

🔧 Configuration

For Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "code-sandbox": {
      "command": "python",
      "args": ["E:/MCP/inkersion-sandbox-mcp/main.py"],
      "env": {
        "DOCKER_HOST": "npipe:////./pipe/docker_engine"
      }
    }
  }
}

Note: Adjust the path to match your installation directory.

For Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "code-sandbox": {
      "command": "python",
      "args": ["/absolute/path/to/main.py"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Docker Host Configuration

Windows (Docker Desktop):

"env": {
  "DOCKER_HOST": "npipe:////./pipe/docker_engine"
}

macOS/Linux (Docker Desktop/Native):

"env": {
  "DOCKER_HOST": "unix:///var/run/docker.sock"
}

macOS (Colima):

"env": {
  "DOCKER_HOST": "unix:///Users/YOUR_USERNAME/.colima/default/docker.sock"
}

🛠️ MCP Tools

The server exposes ten MCP tools spanning both stateless execution and persistent session workflows:

Stateless helpers

• execute_code: Run a one-off script in an isolated container and capture stdout/stderr.
  Use case: Validate a generated snippet before sharing it with a user.
• list_languages: Return metadata for every supported runtime (image, extension, package manager).
  Use case: Choose the right language before spawning a session.
• test_docker: Check Docker connectivity and host resources.
  Use case: Troubleshoot environment issues when executions fail.

Session lifecycle

• sandbox_initialize: Create a persistent container + workspace and optionally preinstall dependencies.
  Use case: Begin a multi-step workflow that needs files or repeated executions.
• sandbox_exec: Execute inline code, existing workspace files, or ad-hoc shell commands within a session.
  Use case: Iterate on code after editing files without recreating the container.
• sandbox_stop: Tear down the session container and delete its workspace.
  Use case: Release resources when a workflow finishes.

Session workspace

• write_file: Write UTF-8 text to any relative path (parent directories auto-created).
  Use case: Upload source files, configs, or fixtures before running code.
• read_file: Read a UTF-8 text file out of the session workspace.
  Use case: Inspect generated outputs or logs mid-session.
• list_files: Enumerate files/directories within the workspace.
  Use case: Discover what the agent has already created.
• install_packages: Install additional dependencies using the language’s package manager.
  Use case: Extend the environment mid-session when new requirements emerge.

💡 Usage Examples

Python with Dependencies

{
  "code": "import requests\nresponse = requests.get('https://api.github.com')\nprint(response.status_code)",
  "language": "python",
  "dependencies": ["requests"]
}

Note: Network is disabled by default, so this example would fail. Remove network_mode="none" from main.py if you need network access.

JavaScript/Node.js

{
  "code": "console.log('Hello from Node.js!');\nconst result = [1,2,3].map(x => x * 2);\nconsole.log(result);",
  "language": "javascript"
}

Bash Script

{
  "code": "#!/bin/bash\necho 'System info:'\nuname -a\necho 'Files:'\nls -la",
  "language": "bash"
}

Go

{
  "code": "package main\nimport \"fmt\"\nfunc main() {\n    fmt.Println(\"Hello from Go!\")\n}",
  "language": "go"
}

Rust

{
  "code": "fn main() {\n    println!(\"Hello from Rust!\");\n    let numbers = vec![1, 2, 3];\n    println!(\"{:?}\", numbers);\n}",
  "language": "rust"
}

🔐 Security Features

• Container Isolation: Each execution runs in a separate Docker container
• Network Isolation: Network access is disabled by default (network_mode="none")
• Resource Limits: Configurable memory limits (default: 512MB)
• Managed Persistence: Stateless containers auto-clean; session containers persist until sandbox_stop
• Read-Only: Code is mounted read-only (configurable)
• Timeout Protection: Execution time limits prevent infinite loops

🎨 Customization

Adding a New Language

Edit LANGUAGE_CONFIGS in main.py:

"your_language": {
    "image": "your-docker-image:tag",
    "extension": ".ext",
    "install_cmd": "package-manager install {packages}",
    "run_cmd": "runtime {file}",
    "common_packages": ["package1", "package2"]
}

Enabling Network Access

If you need network access for certain use cases, modify the container creation in main.py:

container = self.client.containers.run(
    # ...
    network_mode="bridge",  # Change from "none" to "bridge"
    # ...
)

Adjusting Resource Limits

Modify default limits in the execute_code method or pass them as parameters:

memory_limit="1g"  # Increase to 1GB
timeout=60  # Increase to 60 seconds

🐛 Troubleshooting

Docker Connection Error

Error: Docker is not available

Solutions:

1. Ensure Docker Desktop is running
2. Check DOCKER_HOST environment variable
3. Verify Docker socket permissions (Linux/macOS)
4. Try: docker ps to test Docker CLI access

Image Pull Failures

Error: Failed to pull image

Solutions:

1. Check internet connection
2. Verify Docker Hub access
3. Pre-pull images: docker pull python:3.11-slim
4. Check Docker disk space

Permission Denied (Linux/macOS)

Error: Permission denied connecting to Docker socket

Solutions:

# Add user to docker group
sudo usermod -aG docker $USER

# Restart session or run
newgrp docker

Container Timeout

Error: Execution times out

Solutions:

1. Increase timeout parameter
2. Optimize code for better performance
3. Check for infinite loops

📦 Docker Image Pre-pulling

To improve first-run performance, pre-pull commonly used images:

# Pull all images at once
docker pull python:3.11-slim
docker pull node:20-slim
docker pull bash:latest
docker pull golang:1.21-alpine
docker pull rust:1.75-slim
docker pull openjdk:17-slim
docker pull ruby:3.2-slim
docker pull php:8.2-cli

Or use this one-liner:

docker pull python:3.11-slim node:20-slim bash:latest golang:1.21-alpine rust:1.75-slim openjdk:17-slim ruby:3.2-slim php:8.2-cli

🧪 Testing

Test Docker Connection

python -c "from main import DockerCodeSandbox; sandbox = DockerCodeSandbox(); print(sandbox.is_docker_available())"

Test Code Execution

python -c "
from main import DockerCodeSandbox
sandbox = DockerCodeSandbox()
result = sandbox.execute_code('print(\"Hello, World!\")', 'python')
print(result)
"

📚 Related Projects

This project was inspired by and builds upon:

• E2B - Enterprise-grade code execution environments
• CrewAI Code Interpreter - CrewAI's code execution tool
• Daytona - Secure infrastructure for AI-generated code
• Code Interpreter API - Open-source ChatGPT Code Interpreter

🤝 Contributing

Contributions welcome! Areas for improvement:

• Additional language support
• File I/O capabilities
• Persistent workspace mode
• Enhanced security features
• Performance optimizations
• Better error messages

📄 License

MIT License - feel free to use this in your projects!

🆘 Support

If you encounter issues:

1. Check the Troubleshooting section
2. Verify Docker is running: docker ps
3. Check logs for detailed error messages
4. Ensure all dependencies are installed: pip install -r requirements.txt

🎯 Roadmap

• File upload/download support
• Persistent workspace sessions
• Multi-file project support
• GPU support for ML workloads
• Custom Docker images
• Execution history and caching
• Web-based dashboard
• Rate limiting and quotas

Built with ❤️ for AI agents and developers