mcpaisuite-sandboxmcp 1.0.3

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

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

Variable	Default	Description
SANDBOXMCP_BACKEND	process	Execution backend: process or docker
SANDBOXMCP_MAX_CONCURRENT	4	Max concurrent executions
SANDBOXMCP_NETWORK	false	Enable network access
SANDBOXMCP_HOST_ACCESS	false	Enable host command execution
SANDBOXMCP_HOST_AUTO_APPROVE	false	Auto-approve host commands
SANDBOXMCP_VAULT	memory	Vault backend: memory or env
SANDBOXMCP_AUDIT	sqlite	Audit backend: memory or sqlite
SANDBOXMCP_MAX_RAM_MB	512	Max RAM per execution (MB)
SANDBOXMCP_TIMEOUT	60	Execution timeout (seconds)

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

AGPL-3.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [e-mail].