Home

OMCP Python Sandbox - Complete Wiki

Table of Contents

1. Overview
2. Architecture
3. Features
4. Installation
5. Quick Start
6. Usage Guide
7. API Reference
8. Security
9. Development
10. Deployment
11. Troubleshooting
12. Contributing
13. FAQ

---

Overview

The OMCP Python Sandbox is a secure, Model Context Protocol (MCP) compliant Python code execution environment that provides isolated, containerised Python environments for safe code execution. Built with enterprise-grade security features, it enables AI agents and applications to execute Python code without compromising system security.

Key Benefits

• 🔒 Enterprise Security: Docker-based isolation with comprehensive security measures
• 🚀 MCP Compliance: Full Model Context Protocol specification compliance
• ⚡ Fast Execution: Optimised for performance with resource management
• 🛠️ Developer Friendly: Multiple server implementations and debugging tools
• 📊 Production Ready: Robust error handling, logging, and monitoring

Use Cases

• AI Agent Code Execution: Safe Python code execution for AI assistants
• Educational Platforms: Isolated coding environments for learning
• Code Testing: Secure testing environments for untrusted code
• API Services: Python execution as a service
• Development Tools: Local development with sandboxed execution

---

Architecture

System Overview

┌─────────────────┐    JSON-RPC    ┌──────────────────┐    Docker API    ┌─────────────────┐
│   MCP Client    │ ──────────────▶ │  FastMCP Server  │ ────────────────▶ │ Docker Engine   │
│   (Agent/App)   │                │ (server_fastmcp) │                  │                 │
└─────────────────┘                └──────────────────┘                  └─────────────────┘
         │                                   │                                     │
         │                                   │                                     │
         ▼                                   ▼                                     ▼
┌─────────────────┐                ┌──────────────────┐                ┌─────────────────┐
│   MCP Inspector │                │ Sandbox Manager  │                │ Python Sandbox  │
│   (Web UI)      │                │ (src/omcp_py/)   │                │ (Container)     │
└─────────────────┘                └──────────────────┘                └─────────────────┘

Component Details

1. MCP Client Layer

• Purpose: External applications or AI agents that need to execute Python code
• Protocol: JSON-RPC over stdio (MCP specification)
• Tools: create_sandbox, execute_python_code, install_package, list_sandboxes, remove_sandbox

2. FastMCP Server Layer

• Implementation: server_fastmcp.py
• Framework: FastMCP with decorator-based tool definitions
• Features: Enhanced security, timeout handling, structured logging
• Transport: stdio (MCP standard)

3. Sandbox Manager Layer

• Location: src/omcp_py/core/sandbox.py
• Responsibilities:
  • Docker container lifecycle management
  • Resource allocation and cleanup
  • Security policy enforcement
  • Error handling and recovery

4. Docker Container Layer

• Base Image: python:3.11-slim
• Security: Enhanced Docker security options
• Isolation: Complete network and filesystem isolation
• Resources: CPU and memory limits

---

Features

Core Functionality

Sandbox Management

• Create Sandboxes: Instantiate isolated Python environments
• List Sandboxes: Monitor active sandboxes with status information
• Remove Sandboxes: Clean up sandboxes with force options
• Auto-cleanup: Automatic removal of inactive sandboxes

Code Execution

• Python Code Execution: Run arbitrary Python code in isolated containers
• Package Installation: Install Python packages using pip
• Output Capture: Capture stdout, stderr, and exit codes
• JSON Output: Automatic JSON parsing for structured data return

Security Features

• Container Isolation: Each sandbox runs in a separate Docker container
• User Isolation: Containers run as non-root user (sandboxuser)
• Read-only Filesystem: Prevents file system modifications
• Dropped Capabilities: Removes all Linux capabilities
• No Privilege Escalation: Prevents privilege escalation attacks
• Command Injection Protection: Proper command escaping with shlex.quote
• Resource Limits: CPU, memory, and execution time limits
• Network Isolation: Complete network isolation (network_mode="none")
• Timeout Controls: Configurable execution timeouts
• Input Validation: Comprehensive input sanitisation

Development Tools

MCP Inspector Integration

• Web-based Interface: Interactive tool testing at http://127.0.0.1:6274
• Real-time Testing: Test all MCP tools with live feedback
• Request/Response Inspection: View JSON-RPC messages
• Error Debugging: Detailed error messages and stack traces
• Performance Monitoring: Track execution times and resource usage
• Session Persistence: Save and load test scenarios

Multiple Server Implementations

• Standard MCP Server: Full MCP specification compliance (server.py)
• FastMCP Server: Enhanced implementation with decorators (server_fastmcp.py)

---

Installation

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows (with Docker support)
• Python: 3.10 or higher
• Docker: Latest stable version with sudo access
• Node.js: 18.0.0 or higher (for MCP Inspector)

Package Managers

• uv: Modern Python package manager (recommended)
• pip: Traditional Python package manager (alternative)

Installation Steps

1. Clone the Repository

git clone https://github.com/fastomop/omcp_py.git
cd omcp_py

2. Install Python Dependencies

# Using uv (recommended)
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt

3. Install Node.js (for MCP Inspector)

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# macOS
brew install node

# Windows
# Download from https://nodejs.org/

4. Verify Installation

# Check Python dependencies
python -c "import mcp, docker, flask; print('Dependencies OK')"

# Check Node.js
node --version  # Should be 18.0.0 or higher

# Check Docker
sudo docker ps  # Should show Docker is running

Environment Configuration

Optional Environment Variables

Create a .env file in the project root:

# Sandbox Configuration
SANDBOX_TIMEOUT=300
MAX_SANDBOXES=10
DOCKER_IMAGE=python:3.11-slim

# Logging
DEBUG=false
LOG_LEVEL=INFO

# Security
SANDBOX_USER=sandboxuser
SANDBOX_MEMORY_LIMIT=512m
SANDBOX_CPU_LIMIT=0.5

---

Quick Start

1. Start the Server

cd /path/to/omcp_py
source .venv/bin/activate  # If using virtual environment
uv run server_fastmcp.py

2. Launch MCP Inspector (Optional)

In a new terminal:

cd /path/to/omcp_py
npx @modelcontextprotocol/inspector uv run server_fastmcp.py

3. Access Web Interface

Open your browser to: http://127.0.0.1:6274

4. Test Basic Functionality

In the MCP Inspector:

1. Create a sandbox: Use create_sandbox tool
2. Execute code: Use execute_python_code with print("Hello World!")
3. Install package: Use install_package with requests
4. List sandboxes: Use list_sandboxes to see active sandboxes
5. Clean up: Use remove_sandbox when done

---

Usage Guide

Basic Usage Patterns

1. Creating and Using a Sandbox

# Create a new sandbox
result = await mcp.create_sandbox(timeout=300)
sandbox_id = result["sandbox_id"]

# Execute Python code
code_result = await mcp.execute_python_code(
    sandbox_id=sandbox_id,
    code="print('Hello from sandbox!')",
    timeout=30
)

# Clean up
await mcp.remove_sandbox(sandbox_id=sandbox_id, force=True)

2. Installing and Using Packages

# Install a package
await mcp.install_package(
    sandbox_id=sandbox_id,
    package="numpy==1.24.0",
    timeout=60
)

# Use the installed package
code_result = await mcp.execute_python_code(
    sandbox_id=sandbox_id,
    code="""
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print({"sum": arr.sum(), "mean": arr.mean()})
""",
    timeout=30
)

3. Working with Multiple Sandboxes

# Create multiple sandboxes
sandbox1 = await mcp.create_sandbox()
sandbox2 = await mcp.create_sandbox()

# List all sandboxes
sandboxes = await mcp.list_sandboxes(include_inactive=False)

# Execute code in different sandboxes
await mcp.execute_python_code(sandbox_id=sandbox1["sandbox_id"], code="print('Sandbox 1')")
await mcp.execute_python_code(sandbox_id=sandbox2["sandbox_id"], code="print('Sandbox 2')")

---

API Reference

Tool Specifications

create_sandbox

Creates a new isolated Python environment.

Parameters:

• timeout (optional, int): Sandbox timeout in seconds (default: 300)

Returns:

{
  "success": true,
  "sandbox_id": "sandbox_abc123",
  "created_at": "2024-01-01T12:00:00",
  "last_used": "2024-01-01T12:00:00"
}

execute_python_code

Executes Python code in a sandbox.

Parameters:

• sandbox_id (required, string): The sandbox identifier
• code (required, string): Python code to execute
• timeout (optional, int): Execution timeout in seconds (default: 30)

Returns:

{
  "success": true,
  "output": "Hello from sandbox!",
  "error": null,
  "exit_code": 0
}

install_package

Installs a Python package in a sandbox.

Parameters:

• sandbox_id (required, string): The sandbox identifier
• package (required, string): Package name and version (e.g., "numpy==1.24.0")
• timeout (optional, int): Installation timeout in seconds (default: 60)

Returns:

{
  "success": true,
  "output": {"status": "success", "message": "Package installed successfully"},
  "error": null,
  "exit_code": 0
}

list_sandboxes

Lists all active sandboxes.

Parameters:

• include_inactive (optional, boolean): Include inactive sandboxes (default: false)

Returns:

{
  "success": true,
  "sandboxes": [
    {
      "id": "sandbox_abc123",
      "created_at": "2024-01-01T12:00:00",
      "last_used": "2024-01-01T12:00:00"
    }
  ],
  "count": 1
}

remove_sandbox

Removes a sandbox.

Parameters:

• sandbox_id (required, string): The sandbox identifier
• force (optional, boolean): Force removal of active sandboxes (default: false)

Returns:

{
  "success": true,
  "message": "Sandbox sandbox_abc123 removed successfully"
}

---

Security

Security Architecture

Container Security

Each sandbox runs in a Docker container with enhanced security options:

# Docker run options for maximum security
container_config = {
    "image": "python:3.11-slim",
    "user": "sandboxuser",  # Non-root user
    "read_only": True,  # Read-only filesystem
    "tmpfs": {  # Temporary writable areas
        "/tmp": "size=100m",
        "/sandbox": "size=100m"
    },
    "cap_drop": ["ALL"],  # Drop all capabilities
    "security_opt": ["no-new-privileges"],  # No privilege escalation
    "network_mode": "none",  # No network access
    "mem_limit": "512m",  # Memory limit
    "cpus": "0.5",  # CPU limit
    "auto_remove": True  # Auto-cleanup
}

Code Execution Security

• Command Injection Protection: Uses shlex.quote for proper escaping
• List-form Commands: Prevents shell injection attacks
• Input Validation: Comprehensive input sanitisation
• Error Isolation: Errors don't affect other sandboxes

Resource Management

• Maximum Sandboxes: Configurable limit prevents resource exhaustion
• Timeout Controls: Automatic cleanup of long-running operations
• Memory Limits: 512MB per sandbox (configurable)
• CPU Limits: Restricted CPU usage (configurable)

---

Development

Project Structure

omcp_py/
├── src/
│   └── omcp_py/
│       ├── core/
│       │   └── sandbox.py          # Sandbox management
│       ├── tools/
│       │   ├── execution_tools.py  # Code execution tools
│       │   └── sandbox_tools.py    # Sandbox management tools
│       └── utils/
│           └── config.py           # Configuration management
├── server.py                       # Standard MCP server
├── server_fastmcp.py               # FastMCP server (enhanced)
├── sandbox_server.py               # Flask sandbox server
├── Dockerfile                      # Docker image definition
├── requirements.txt                # Python dependencies
├── pyproject.toml                  # Project configuration
└── README.md                       # Project documentation

Development Setup

1. Clone and Setup

git clone https://github.com/fastomop/omcp_py.git
cd omcp_py
uv pip install -r requirements.txt

2. Install Development Dependencies

uv pip install -r requirements.txt[dev]

3. Run Tests

pytest

4. Code Formatting

black .
ruff check .

---

Troubleshooting

Common Issues

1. Docker Issues

Problem: Docker permission errors

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

Problem: Docker daemon not running

# Solution: Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

2. MCP Inspector Issues

Problem: Inspector not starting

# Check Node.js version
node --version  # Should be 18.0.0+

# Reinstall inspector
npm uninstall -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector --version

Problem: Port already in use

# Check what's using the port
ss -tlnp | grep 6274

# Kill the process if needed
sudo kill -9 <PID>

3. Sandbox Issues

Problem: Sandbox creation fails

# Check Docker resources
sudo docker system df
sudo docker system prune

# Check logs
docker logs <container_id>

Problem: Code execution timeout

# Increase timeout values
export SANDBOX_TIMEOUT=600
export EXECUTION_TIMEOUT=120

Debugging Tools

1. MCP Inspector

• Use for interactive debugging
• View request/response data
• Test individual tools

2. Docker Commands

# List containers
sudo docker ps -a

# Inspect container
sudo docker inspect <container_id>

# View container logs
sudo docker logs <container_id>

# Execute in container
sudo docker exec -it <container_id> /bin/bash

---

FAQ

General Questions

Q: What is MCP?

A: Model Context Protocol (MCP) is a specification for AI agents to interact with external tools and data sources. It provides a standardised way for AI assistants to execute code, access databases, and interact with external services.

Q: Why use Docker for sandboxing?

A: Docker provides strong isolation between sandboxes, preventing code from accessing the host system or other sandboxes. It also offers resource limits, security options, and easy cleanup.

Security Questions

Q: How secure is the sandboxing?

A: The sandboxing uses multiple layers of security:

• Docker container isolation
• Non-root user execution
• Read-only filesystem
• Dropped Linux capabilities
• Network isolation
• Resource limits

Q: Can malicious code escape the sandbox?

A: While no security system is 100% perfect, the multiple layers of security makes it difficult for malicious code to escape. The system is designed to prevent privilege escalation and system access.

Performance Questions

Q: How fast is sandbox creation?

A: Sandbox creation typically takes 1-3 seconds, depending on system resources and Docker image caching. Subsequent operations within the same sandbox are very fast.

Q: How many sandboxes can I run simultaneously?

A: The number depends on your system resources. Each sandbox uses ~512MB of memory and limited CPU. The default limit is 10 sandboxes, but this is configurable.

Integration Questions

Q: How do I integrate with my AI agent?

A: The OMCP Python Sandbox follows the MCP specification, so it can be integrated with any MCP-compliant AI agent. Simply configure the agent to use the server's stdio transport.

Q: How do I monitor sandbox usage?

A: Use the list_sandboxes tool to monitor active sandboxes, and implement logging and metrics collection for production monitoring.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review the documentation
• Use the MCP Inspector for debugging

---

Last Updated: June 2024
Version: 0.2.1
Maintainer: Zhangshu Joshua Jiang and the wider FastOMOP team.