Sandbox provides a secure, production-ready Python execution environment designed for executing code, managing artifacts, and integrating seamlessly with AI models through its comprehensive MCP server.

How does Sandbox enhance Python code execution?

It offers a sandboxed environment with persistent context, an interactive REPL, enhanced error handling, and robust security features like command filtering, timeout control, and resource monitoring for safe and reliable execution.

What types of artifacts does Sandbox manage, and how?

Sandbox automatically captures and organizes a wide range of artifacts including Matplotlib plots, PIL images, structured data (JSON, CSV), and video outputs from Manim animations, with smart categorization and cleanup options.

Can Sandbox integrate with AI models or host web applications?

Yes, Sandbox features a production-ready MCP server specifically designed for seamless integration with AI models like LM Studio. It also supports hosting Flask and Streamlit web applications directly, providing accessible URLs.

주요 기능

01Automated Artifact Capture and Management for plots, images, and structured data

02Manim Mathematical Animation Generation with video output and example library

03Integrated Flask and Streamlit Web Application Hosting with URL generation

04Production-ready MCP Server for seamless integration with AI models like LM Studio

050 GitHub stars

06Secure Sandboxed Python Execution with persistent context and interactive REPL

Enhanced Sandbox SDK

Name: Sandbox
Author: scooter-lacroix

Production-ready Python sandbox execution environment with comprehensive MCP server support, featuring enhanced artifact management, interactive REPL, and Manim animation capabilities.

🎬 Demo: Manim Animation in Action

See the Sandbox MCP server creating beautiful mathematical animations with Manim:

Alternative formats: MP4 Video | GIF Animation

Example: 3D mathematical animation generated automatically by the sandbox

🚀 Quick Start

# Clone the repository
git clone https://github.com/scooter-lacroix/sandbox-mcp.git
cd sandbox-mcp

# Install with uv (recommended)
uv venv && uv pip install -e .

# Run the MCP server
uv run sandbox-server-stdio

✨ Features

🔧 Enhanced Python Execution

Code Validation: Automatic input validation and formatting
Virtual Environment: Auto-detects and activates .venv
Persistent Context: Variables persist across executions
Enhanced Error Handling: Detailed diagnostics with colored output
Interactive REPL: Real-time Python shell with tab completion

🎨 Intelligent Artifact Management

Automatic Capture: Matplotlib plots and PIL images
Categorization: Smart file type detection and organization
Multiple Formats: JSON, CSV, and structured output
Recursive Scanning: Deep directory traversal
Smart Cleanup: Configurable cleanup by type or age

🎬 Manim Animation Support

Pre-compiled Examples: One-click animation execution
Quality Control: Multiple rendering presets
Video Generation: Auto-saves MP4 animations
Example Library: Built-in templates and tutorials
Environment Verification: Automatic dependency checking

🌐 Web Application Hosting

Flask & Streamlit: Launch web apps with auto port detection
Process Management: Track and manage running servers
URL Generation: Returns accessible endpoints

🔒 Security & Safety

Command Filtering: Blocks dangerous operations
Sandboxed Execution: Isolated environment
Timeout Control: Configurable execution limits
Resource Monitoring: Memory and CPU usage tracking

🔌 MCP Integration

Dual Transport: HTTP and stdio support
LM Studio Ready: Drop-in AI model integration
FastMCP Powered: Modern MCP implementation
Comprehensive Tools: 12+ available MCP tools

📦 Installation

Prerequisites

Python 3.9+
uv (recommended) or pip

Method 1: Direct Git Installation (Recommended)

For immediate use with AI applications like LM Studio, Claude Desktop, or VS Code:

uvx git+https://github.com/scooter-lacroix/sandbox-mcp.git

This automatically installs and runs the MCP server without manual setup.

Method 2: Local Development Installation

For development, customization, or contributing:

Using uv (Recommended)

git clone https://github.com/scooter-lacroix/sandbox-mcp.git
cd sandbox-mcp
uv venv
uv pip install -e .

Using pip

git clone https://github.com/scooter-lacroix/sandbox-mcp.git
cd sandbox-mcp
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows
pip install -e .

Method 3: Package Installation

Install from package manager (when available):

# Using uv
uvx sandbox-mcp

# Using pip
pip install sandbox-mcp

🖥️ Usage

Command Line Interface

# Start HTTP server (web integration)
sandbox-server

# Start stdio server (LM Studio integration)
sandbox-server-stdio

MCP Integration

The Sandbox MCP server supports multiple integration methods:

Method 1: Direct Git Integration (Recommended)

For LM Studio, Claude Desktop, VS Code, and other MCP-compatible applications:

{
  "mcpServers": {
    "sandbox": {
      "command": "uvx",
      "args": ["git+https://github.com/scooter-lacroix/sandbox-mcp.git"],
      "env": {},
      "start_on_launch": true
    }
  }
}

Method 2: Local Installation

For locally installed versions:

{
  "mcpServers": {
    "sandbox": {
      "command": "sandbox-server-stdio",
      "args": [],
      "env": {},
      "start_on_launch": true
    }
  }
}

Method 3: HTTP Server Mode

For web-based integrations:

# Start HTTP server
python -m sandbox.mcp_sandbox_server --port 8765

Then configure your application:

{
  "mcpServers": {
    "sandbox": {
      "transport": "http",
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Application-Specific Configurations

VS Code/Cursor/Windsurf (using MCP extension):

{
  "mcp.servers": {
    "sandbox": {
      "command": "sandbox-server-stdio",
      "args": [],
      "env": {},
      "transport": "stdio"
    }
  }
}

Jan AI:

{
  "mcp_servers": {
    "sandbox": {
      "command": "sandbox-server-stdio",
      "args": [],
      "env": {}
    }
  }
}

OpenHands:

{
  "mcp": {
    "servers": {
      "sandbox": {
        "command": "sandbox-server-stdio",
        "args": [],
        "env": {}
      }
    }
  }
}

Available MCP Tools

Tool	Description
`execute`	Execute Python code with artifact capture
`shell_execute`	Execute shell commands safely with security filtering
`list_artifacts`	List generated artifacts
`cleanup_artifacts`	Clean up temporary files
`get_execution_info`	Get environment diagnostics
`start_repl`	Start interactive session
`start_web_app`	Launch Flask/Streamlit apps
`cleanup_temp_artifacts`	Maintenance operations
`create_manim_animation`	Create mathematical animations using Manim
`list_manim_animations`	List all created Manim animations
`cleanup_manim_animation`	Clean up specific animation files
`get_manim_examples`	Get example Manim code snippets

💡 Examples

Enhanced SDK Usage

Local Python Execution

import asyncio
from sandbox import PythonSandbox

async def local_example():
    async with PythonSandbox.create_local(name="my-sandbox") as sandbox:
        # Execute Python code
        result = await sandbox.run("print('Hello from local sandbox!')")
        print(await result.output())
        
        # Execute code with artifacts
        plot_code = """
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.figure(figsize=(8, 6))
plt.plot(x, y)
plt.title('Sine Wave')
plt.show()  # Automatically captured as artifact
"""
        result = await sandbox.run(plot_code)
        print(f"Artifacts created: {result.artifacts}")
        
        # Execute shell commands
        cmd_result = await sandbox.command.run("ls", ["-la"])
        print(await cmd_result.output())

asyncio.run(local_example())

Remote Python Execution (with microsandbox)

import asyncio
from sandbox import PythonSandbox

async def remote_example():
    async with PythonSandbox.create_remote(
        server_url="http://127.0.0.1:5555",
        api_key="your-api-key",
        name="remote-sandbox"
    ) as sandbox:
        # Execute Python code in secure microVM
        result = await sandbox.run("print('Hello from microVM!')")
        print(await result.output())
        
        # Get sandbox metrics
        metrics = await sandbox.metrics.all()
        print(f"CPU usage: {metrics.get('cpu_usage', 0)}%")
        print(f"Memory usage: {metrics.get('memory_usage', 0)} MB")

asyncio.run(remote_example())

Node.js Execution

import asyncio
from sandbox import NodeSandbox

async def node_example():
    async with NodeSandbox.create(
        server_url="http://127.0.0.1:5555",
        api_key="your-api-key",
        name="node-sandbox"
    ) as sandbox:
        # Execute JavaScript code
        js_code = """
console.log('Hello from Node.js!');
const sum = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0);
console.log(`Sum: ${sum}`);
"""
        result = await sandbox.run(js_code)
        print(await result.output())

asyncio.run(node_example())

Builder Pattern Configuration

import asyncio
from sandbox import LocalSandbox, SandboxOptions

async def builder_example():
    config = (SandboxOptions.builder()
              .name("configured-sandbox")
              .memory(1024)
              .cpus(2.0)
              .timeout(300.0)
              .env("DEBUG", "true")
              .build())
    
    async with LocalSandbox.create(**config.__dict__) as sandbox:
        result = await sandbox.run("import os; print(os.environ.get('DEBUG'))")
        print(await result.output())  # Should print: true

asyncio.run(builder_example())

MCP Server Examples

Basic Python Execution

# Execute simple code
result = execute(code="print('Hello, World!')")

Matplotlib Artifact Generation

code = """
import matplotlib.pyplot as plt
import numpy as np

# Generate plot
x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.figure(figsize=(8, 6))
plt.plot(x, y, 'b-', linewidth=2)
plt.title('Sine Wave')
plt.xlabel('x')
plt.ylabel('sin(x)')
plt.grid(True)
plt.show()  # Automatically captured as artifact
"""

result = execute(code)
# Returns JSON with base64-encoded PNG

Flask Web Application

flask_code = """
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/')
def home():
    return '<h1>Sandbox Flask App</h1>'

@app.route('/api/status')
def status():
    return jsonify({"status": "running", "server": "sandbox"})
"""

result = start_web_app(flask_code, "flask")
# Returns URL where app is accessible

Shell Command Execution

# Install packages via shell
result = shell_execute("uv pip install matplotlib")

# Check environment
result = shell_execute("which python")

# List directory contents
result = shell_execute("ls -la")

# Custom working directory and timeout
result = shell_execute(
    "find . -name '*.py' | head -10", 
    working_directory="/path/to/search",
    timeout=60
)

Manim Animation Creation

# Simple circle animation
manim_code = """
from manim import *

class SimpleCircle(Scene):
    def construct(self):
        circle = Circle()
        circle.set_fill(PINK, opacity=0.5)
        self.play(Create(circle))
        self.wait(1)
"""

result = create_manim_animation(manim_code, quality="medium_quality")
# Returns JSON with video path and metadata

# Mathematical graph visualization
math_animation = """
from manim import *

class GraphPlot(Scene):
    def construct(self):
        axes = Axes(
            x_range=[-3, 3, 1],
            y_range=[-3, 3, 1],
            x_length=6,
            y_length=6
        )
        axes.add_coordinates()
        
        graph = axes.plot(lambda x: x**2, color=BLUE)
        graph_label = axes.get_graph_label(graph, label="f(x) = x^2")
        
        self.play(Create(axes))
        self.play(Create(graph))
        self.play(Write(graph_label))
        self.wait(1)
"""

result = create_manim_animation(math_animation, quality="high_quality")

# List all animations
animations = list_manim_animations()

# Get example code snippets
examples = get_manim_examples()

Error Handling

# Import error with detailed diagnostics
result = execute(code="import nonexistent_module")
# Returns structured error with sys.path info

# Security-blocked shell command
result = shell_execute("rm -rf /")
# Returns security error with blocked pattern info

🏗️ Architecture

Project Structure

sandbox-mcp/
├── src/
│   └── sandbox/                   # Main package
│       ├── __init__.py           # Package initialization
│       ├── mcp_sandbox_server.py # HTTP MCP server
│       ├── mcp_sandbox_server_stdio.py # stdio MCP server
│       ├── server/               # Server modules
│       │   ├── __init__.py
│       │   └── main.py
│       └── utils/                # Utility modules
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── test_integration.py       # Main test suite
│   └── test_simple_integration.py
├── pyproject.toml                # Package configuration
├── README.md                     # This file
├── .gitignore
└── uv.lock                       # Dependency lock file

Core Components

ExecutionContext

Manages the execution environment:

Project Root Detection: Dynamic path resolution
Virtual Environment: Auto-detection and activation
sys.path Management: Intelligent path handling
Artifact Management: Temporary directory lifecycle
Global State: Persistent execution context

Monkey Patching System

Non-intrusive artifact capture:

matplotlib.pyplot.show(): Intercepts and saves plots
PIL.Image.show(): Captures image displays
Conditional Patching: Only applies if libraries available
Original Functionality: Preserved through wrapper functions

MCP Integration

FastMCP-powered server with:

Dual Transport: HTTP and stdio protocols
Tool Registry: 7 available MCP tools
Streaming Support: Ready for real-time interaction
Error Handling: Structured error responses

📚 Documentation

For comprehensive usage information, troubleshooting guides, and advanced features:

FAQ and Limitations - Common issues and sandbox restrictions
Enhanced Features Guide - Advanced capabilities and examples
API Reference - Complete API documentation

🧪 Testing

Run the test suite to verify installation:

uv run pytest tests/ -v

Test categories include:

Package import and sys.path tests
Error handling and ImportError reporting
Artifact capture (matplotlib/PIL)
Web application launching
Virtual environment detection

🤝 Contributing

Fork the repository
Create a feature branch
Run tests: uv run pytest
Submit a pull request

For development setup:

uv venv && uv pip install -e ".[dev]"

License

Apache License

Attribution

This project includes minor inspiration from:

Microsandbox - Referenced for secure microVM isolation concepts

The majority of the functionality in this project is original implementation focused on MCP server integration and enhanced Python execution environments.

Changelog

v0.3.0 (Enhanced SDK Release)

🚀 Enhanced SDK: Complete integration with microsandbox functionality
🔄 Unified API: Single interface for both local and remote execution
🛡️ MicroVM Support: Secure remote execution via microsandbox server
🌐 Multi-Language: Python and Node.js execution environments
🏗️ Builder Pattern: Fluent configuration API with SandboxOptions
📊 Metrics & Monitoring: Real-time resource usage tracking
⚡ Async/Await: Modern Python async support throughout
🔒 Enhanced Security: Improved command filtering and validation
📦 Artifact Management: Comprehensive file artifact handling
🎯 Command Execution: Safe shell command execution with timeouts
🔧 Configuration: Flexible sandbox configuration options
📝 Documentation: Comprehensive examples and usage guides

v0.2.0

Manim Integration: Complete mathematical animation support
4 New MCP Tools: create_manim_animation, list_manim_animations, cleanup_manim_animation, get_manim_examples
Quality Control: Multiple animation quality presets
Video Artifacts: Auto-saves MP4 animations to artifacts directory
Example Library: Built-in Manim code examples
Virtual Environment Manim: Uses venv-installed Manim executable

v0.1.0

Initial enhanced package structure
Dynamic project root detection
Robust virtual environment integration
Enhanced error handling with detailed tracebacks
Artifact management with matplotlib/PIL support
Web application launching (Flask/Streamlit)
Comprehensive test suite
MCP server integration (HTTP and stdio)
CLI entry points
LM Studio compatibility

주요 기능

01Automated Artifact Capture and Management for plots, images, and structured data

02Manim Mathematical Animation Generation with video output and example library

03Integrated Flask and Streamlit Web Application Hosting with URL generation

04Production-ready MCP Server for seamless integration with AI models like LM Studio

050 GitHub stars

06Secure Sandboxed Python Execution with persistent context and interactive REPL

# Clone the repository git clone https://github.com/scooter-lacroix/sandbox-mcp.git cd sandbox-mcp # Install with uv (recommended) uv venv && uv pip install -e . # Run the MCP server uv run sandbox-server-stdio

Tool

Description

execute

Execute Python code with artifact capture

shell_execute

Execute shell commands safely with security filtering

list_artifacts

List generated artifacts

cleanup_artifacts

Clean up temporary files

get_execution_info

Get environment diagnostics

start_repl

Start interactive session

start_web_app

Launch Flask/Streamlit apps

cleanup_temp_artifacts

Maintenance operations

create_manim_animation

Create mathematical animations using Manim

list_manim_animations

List all created Manim animations

cleanup_manim_animation

Clean up specific animation files

get_manim_examples

Get example Manim code snippets

import asyncio from sandbox import PythonSandbox async def local_example(): async with PythonSandbox.create_local(name="my-sandbox") as sandbox: # Execute Python code result = await sandbox.run("print('Hello from local sandbox!')") print(await result.output()) # Execute code with artifacts plot_code = """ import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 10, 100) y = np.sin(x) plt.figure(figsize=(8, 6)) plt.plot(x, y) plt.title('Sine Wave') plt.show() # Automatically captured as artifact """ result = await sandbox.run(plot_code) print(f"Artifacts created: {result.artifacts}") # Execute shell commands cmd_result = await sandbox.command.run("ls", ["-la"]) print(await cmd_result.output()) asyncio.run(local_example())

import asyncio from sandbox import PythonSandbox async def remote_example(): async with PythonSandbox.create_remote( server_url="http://127.0.0.1:5555", api_key="your-api-key", name="remote-sandbox" ) as sandbox: # Execute Python code in secure microVM result = await sandbox.run("print('Hello from microVM!')") print(await result.output()) # Get sandbox metrics metrics = await sandbox.metrics.all() print(f"CPU usage: {metrics.get('cpu_usage', 0)}%") print(f"Memory usage: {metrics.get('memory_usage', 0)} MB") asyncio.run(remote_example())

import asyncio from sandbox import NodeSandbox async def node_example(): async with NodeSandbox.create( server_url="http://127.0.0.1:5555", api_key="your-api-key", name="node-sandbox" ) as sandbox: # Execute JavaScript code js_code = """ console.log('Hello from Node.js!'); const sum = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0); console.log(`Sum: ${sum}`); """ result = await sandbox.run(js_code) print(await result.output()) asyncio.run(node_example())

import asyncio from sandbox import LocalSandbox, SandboxOptions async def builder_example(): config = (SandboxOptions.builder() .name("configured-sandbox") .memory(1024) .cpus(2.0) .timeout(300.0) .env("DEBUG", "true") .build()) async with LocalSandbox.create(**config.__dict__) as sandbox: result = await sandbox.run("import os; print(os.environ.get('DEBUG'))") print(await result.output()) # Should print: true asyncio.run(builder_example())

code = """ import matplotlib.pyplot as plt import numpy as np # Generate plot x = np.linspace(0, 10, 100) y = np.sin(x) plt.figure(figsize=(8, 6)) plt.plot(x, y, 'b-', linewidth=2) plt.title('Sine Wave') plt.xlabel('x') plt.ylabel('sin(x)') plt.grid(True) plt.show() # Automatically captured as artifact """ result = execute(code) # Returns JSON with base64-encoded PNG

flask_code = """ from flask import Flask, jsonify app = Flask(__name__) @app.route('/') def home(): return '<h1>Sandbox Flask App</h1>' @app.route('/api/status') def status(): return jsonify({"status": "running", "server": "sandbox"}) """ result = start_web_app(flask_code, "flask") # Returns URL where app is accessible

# Install packages via shell result = shell_execute("uv pip install matplotlib") # Check environment result = shell_execute("which python") # List directory contents result = shell_execute("ls -la") # Custom working directory and timeout result = shell_execute( "find . -name '*.py' | head -10", working_directory="/path/to/search", timeout=60 )

# Simple circle animation manim_code = """ from manim import * class SimpleCircle(Scene): def construct(self): circle = Circle() circle.set_fill(PINK, opacity=0.5) self.play(Create(circle)) self.wait(1) """ result = create_manim_animation(manim_code, quality="medium_quality") # Returns JSON with video path and metadata # Mathematical graph visualization math_animation = """ from manim import * class GraphPlot(Scene): def construct(self): axes = Axes( x_range=[-3, 3, 1], y_range=[-3, 3, 1], x_length=6, y_length=6 ) axes.add_coordinates() graph = axes.plot(lambda x: x**2, color=BLUE) graph_label = axes.get_graph_label(graph, label="f(x) = x^2") self.play(Create(axes)) self.play(Create(graph)) self.play(Write(graph_label)) self.wait(1) """ result = create_manim_animation(math_animation, quality="high_quality") # List all animations animations = list_manim_animations() # Get example code snippets examples = get_manim_examples()

# Import error with detailed diagnostics result = execute(code="import nonexistent_module") # Returns structured error with sys.path info # Security-blocked shell command result = shell_execute("rm -rf /") # Returns security error with blocked pattern info

sandbox-mcp/ ├── src/ │ └── sandbox/ # Main package │ ├── __init__.py # Package initialization │ ├── mcp_sandbox_server.py # HTTP MCP server │ ├── mcp_sandbox_server_stdio.py # stdio MCP server │ ├── server/ # Server modules │ │ ├── __init__.py │ │ └── main.py │ └── utils/ # Utility modules │ ├── __init__.py │ └── helpers.py ├── tests/ │ ├── test_integration.py # Main test suite │ └── test_simple_integration.py ├── pyproject.toml # Package configuration ├── README.md # This file ├── .gitignore └── uv.lock # Dependency lock file

주요 기능

사용 사례

Enhanced Sandbox SDK

🎬 Demo: Manim Animation in Action

🚀 Quick Start

✨ Features

🔧 Enhanced Python Execution

🎨 Intelligent Artifact Management

🎬 Manim Animation Support

🌐 Web Application Hosting

🔒 Security & Safety

🔌 MCP Integration

📦 Installation

Prerequisites

Method 1: Direct Git Installation (Recommended)

Method 2: Local Development Installation

Using uv (Recommended)

Using pip

Method 3: Package Installation

🖥️ Usage

Command Line Interface

MCP Integration

Method 1: Direct Git Integration (Recommended)

Method 2: Local Installation

Method 3: HTTP Server Mode

Application-Specific Configurations

Available MCP Tools

💡 Examples

Enhanced SDK Usage

Local Python Execution

Remote Python Execution (with microsandbox)

Node.js Execution

Builder Pattern Configuration

MCP Server Examples

Basic Python Execution

Matplotlib Artifact Generation

Flask Web Application

Shell Command Execution

Manim Animation Creation

Error Handling

🏗️ Architecture

Project Structure

Core Components

ExecutionContext

Monkey Patching System

MCP Integration

📚 Documentation

🧪 Testing

🤝 Contributing

License

Attribution

Changelog

v0.3.0 (Enhanced SDK Release)

v0.2.0

v0.1.0

주요 기능

사용 사례

Enhanced Sandbox SDK

🎬 Demo: Manim Animation in Action

🚀 Quick Start

✨ Features

🔧 Enhanced Python Execution

🎨 Intelligent Artifact Management

🎬 Manim Animation Support

🌐 Web Application Hosting

🔒 Security & Safety

🔌 MCP Integration

📦 Installation

Prerequisites

Method 1: Direct Git Installation (Recommended)

Method 2: Local Development Installation

Using uv (Recommended)

Using pip

Method 3: Package Installation

🖥️ Usage

Command Line Interface

MCP Integration

Method 1: Direct Git Integration (Recommended)

Method 2: Local Installation

Method 3: HTTP Server Mode