sandboxmcp

Secure, polyglot code execution engine for AI agents with MCP support

Part of the MCP AI Suite.

Features

• Polyglot execution -- run Python, JavaScript (Node), and shell in isolated environments
• Process backend for zero-dependency local execution with resource limits
• Docker hardened mode -- fully isolated containers with memory limits, CPU quotas, and network control
• Code validation with auto-fix for common issues and dangerous-pattern rejection
• Secret vault -- in-memory or environment-based credential injection without exposing secrets to agent output
• Network egress control -- global allowlist of permitted domains, default deny-all
• Host access guard -- optional controlled access to host commands with allow/block lists and auto-approve mode
• Web tools -- web search, page fetching, and browser rendering (lazily delegated to websearchmcp; requires the optional browser extra)
• Full audit logging via SQLite -- every execution, approval, and security event recorded

Installation

pip install mcpaisuite-sandboxmcp
# Optional extras:
pip install "mcpaisuite-sandboxmcp[docker]"        # Docker backend support
pip install "mcpaisuite-sandboxmcp[browser]"       # Web tools (web_search / fetch_webpage / browser_fetch via websearchmcp)
pip install "mcpaisuite-sandboxmcp[workspacemcp]"  # workspacemcp suite integration
pip install "mcpaisuite-sandboxmcp[planningmcp]"   # planningmcp suite integration
pip install "mcpaisuite-sandboxmcp[dev]"           # Development tools
pip install "mcpaisuite-sandboxmcp[all]"           # Docker + browser + suite integrations

The web tools (web_search, fetch_webpage, browser_fetch) are lazily imported from websearchmcp at call time and require the browser extra (or all). Without it, those tools raise an import error while the rest of sandboxmcp works normally.

Quick Start

from sandboxmcp import SandboxFactory, ExecutionRequest, Language

sandbox = SandboxFactory.default()
result = await sandbox.execute(ExecutionRequest(
    code='print("Hello from sandbox!")',
    language=Language.python,
))
print(result.stdout)  # "Hello from sandbox!"

MCP Server

sandboxmcp serve

Configuration

Docker Hardened Mode

For maximum isolation, use the Docker backend:

sandbox = SandboxFactory.create(
    default_backend="docker",
    image="python:3.12-slim",
    memory_limit="256m",
    network_mode="none",
)

This runs each execution in a disposable container with enforced memory limits, CPU quotas, and no network access.

API Reference

SandboxPipeline

The central orchestrator for code execution with full security pipeline.

await sandbox.execute(request: ExecutionRequest) -> SandboxResult
await sandbox.create_session(language, namespace) -> Session
await sandbox.execute_in_session(session_id, code) -> SandboxResult
await sandbox.list_sessions() -> list[Session]

SandboxFactory

SandboxFactory.default()                 # Process backend, in-memory vault, no network
SandboxFactory.from_env()                # Build from environment variables
SandboxFactory.from_yaml("config.yaml")  # Build from YAML config
SandboxFactory.create(default_backend="docker", enable_network=True, ...)

Architecture

SandboxPipeline orchestrates a security pipeline: incoming code passes through CodeValidator (syntax check, dangerous-pattern scan, auto-fix), then to the execution backend (Process or Docker), with NetworkGuard controlling egress and InMemoryVault injecting secrets. An AsyncJobQueue manages concurrency, and all events are recorded by the audit logger.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

Apache-2.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact contact@mcpaisuite.com.