py-sandbox
LostSyscall/pysandbox
Executor Python seguro em sandbox com suporte MCP para agentes IA
Ver no GitHubExecutor de código Python isolado em sandbox com suporte a MCP (Model Context Protocol). Fornece um ambiente seguro para executar código Python arbitrário com validação AST, restrições de built-ins, whitelist de importações e limites de recursos (timeout, memória, output).
Instalação
npx convez-ai LostSyscall/pysandbox1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar código Python não confiável de forma segura em agentes IA
- Avaliar e testar snippets de código com isolamento de recursos
- Plataformas de execução de código com proteção contra exploits
Veredito

Solução robusta para execução segura de código Python em ambientes não confiáveis. Implementa múltiplas camadas de proteção (AST, builtins restritos, whitelist, isolamento de processo) e integra-se nativamente com o ecossistema Claude via MCP, sendo ideal para agentes que precisam executar código arbitrário.
README
A tradução para o português deste README ainda está na fila.
py-sandbox
A cross-platform sandboxed Python code executor with MCP (Model Context Protocol) server support.
Overview
py-sandbox provides a secure environment for executing arbitrary Python code with strict resource limits and security constraints. It is designed for use in AI agent systems, code evaluation platforms, and any scenario where untrusted Python code needs to be run safely.
The sandbox operates through a multi-layered security model:
- AST Validation — Rejects dangerous code patterns before execution
- Restricted Builtins — Limits available built-in functions inside the sandbox
- Import Whitelist — Only safe modules (math, json, re, etc.) can be imported
- Subprocess Isolation — Code runs in a separate process, not the host
- Resource Limits — Timeout, memory, and output size are all enforced
Features
- Cross-platform — Works on Windows, macOS, and Linux
- Windows: Job Objects + watchdog for memory/timeout enforcement
- Unix:
setrlimitviapreexec_fn+ watchdog
- MCP Server — Expose
run_pythontool to AI agents via stdio or SSE transport - CLI Tool — Direct sandbox execution from the command line
- Variable Inspection — Inspect named variables after execution
- Output Limiting — Truncate excessive stdout to prevent resource abuse
- No External Dependencies — Core sandbox uses only Python stdlib (ctypes on Windows)
Installation
# Core sandbox (no MCP server)
pip install py-sandbox
# With MCP server support
pip install py-sandbox[mcp]
# Using uv
uv pip install py-sandbox
uv pip install py-sandbox[mcp]
For development:
git clone https://github.com/LostSyscall/pysandbox.git
cd py-sandbox-mcp
uv sync
Usage
CLI
# Execute inline code
py-sandbox "print('hello world')"
# Execute from a file
py-sandbox -f script.py
# With resource limits
py-sandbox -t 10 -m 128 "import math; print(math.pi)"
# Inspect variables
py-sandbox -v x -v y "x = 42; y = [1, 2, 3]"
Options:
| Option | Default | Max | Description |
|---|---|---|---|
-t / --timeout | 30 | 60 | Timeout in seconds |
-m / --memory | 256 | 1024 | Memory limit in MB |
-o / --output-limit | 65536 | 262144 | Output limit in bytes |
-v / --variables | — | — | Variable names to inspect |
Python API
from py_sandbox import execute
result = execute("import math; print(math.sqrt(16))")
print(result["stdout"]) # "4.0"
print(result["return_code"]) # 0
result = execute("x = 42", inspect_variables=["x"])
print(result["variables"]) # {"x": 42}
result = execute("import os")
print(result["error"]) # "Import of module 'os' is not allowed..."
print(result["return_code"]) # -1
MCP Server
Start the MCP server for AI agent integration:
# stdio transport (default, for CLI-based agents)
py-sandbox-mcp
# SSE transport (for HTTP-based agents)
py-sandbox-mcp sse
The server exposes a run_python tool with the same parameters as the execute() function.
Example MCP client configuration (for Claude Code, Cursor, etc.):
{
"mcpServers": {
"python-sandbox": {
"command": "py-sandbox-mcp",
"args": []
}
}
}
Security Model
Layer 1: AST Validation
The AST validator rejects code before it ever reaches execution. Blocked patterns include:
- Dangerous imports —
os,sys,subprocess,socket,ctypes,pickle, etc. - Dangerous builtins —
exec,eval,compile,open,__import__,getattr, etc. - Dunder escapes —
__class__,__subclasses__,__globals__,__builtins__, etc. - Dynamic class creation —
type()with 3 arguments - Relative imports — Not allowed (sandbox code has no package context)
- String-based dunder references —
hasattr(obj, "__class__")is blocked
Layer 2: Restricted Builtins
The sandbox worker replaces __builtins__ with a safe subset. Only essential functions like len, range, print, sorted, isinstance, etc. are available. Dangerous builtins like open, exec, eval, getattr are removed.
Layer 3: Import Whitelist
Only these modules can be imported inside the sandbox:
- Math:
math,cmath,decimal,fractions,statistics - Data:
json,re,string,textwrap,unicodedata,difflib - Time:
datetime,calendar - Collections:
collections,itertools,functools,operator,enum,dataclasses,typing,copy - Encoding:
hashlib,base64,random,uuid,struct - Utility:
pprint
All other imports raise ImportError.
Layer 4: Subprocess Isolation
Code executes in a separate subprocess, not the host process. This means:
- The sandbox process cannot access the host's memory or state
- When the host kills the sandbox process, all its resources are reclaimed
- No shared file descriptors, no signal leakage
Layer 5: Resource Limits
| Resource | Enforcement |
|---|---|
| Timeout | Watchdog thread + Unix RLIMIT_CPU / Windows Job Object time limit |
| Memory | Watchdog polling + Unix RLIMIT_AS / Windows Job Object memory limit |
| Output | Byte-counted stdout truncation inside the worker |
| File descriptors | Unix RLIMIT_NOFILE (limited to 64) |
Architecture
flowchart TB
subgraph host["Host Process"]
entry["CLI / MCP Server"]
executor["Executor (Orchestrator)"]
ast["AST Validator\n(reject or accept)"]
platform["Platform Utils\n(Job Object / setrlimit)"]
watchdog["ResourceWatchdog\n(timeout / memory)"]
end
subgraph worker["Sandbox Worker (subprocess)"]
builtins["Restricted __builtins__\n+ Import Whitelist"]
exec_code["exec(code, namespace)"]
output["Output limiting (byte count)\nVariable serialization"]
end
entry --> executor
executor --> ast
executor --> platform
executor --> watchdog
executor -- "spawn subprocess\nstdin: JSON envelope" --> worker
worker -- "stdout: JSON result" --> executor
Execution Flow
- CLI or MCP Server receives code to execute
- Executor validates code through the AST Validator — if rejected, returns error immediately
- Platform Utils sets up OS-level resource limits (Job Object on Windows,
setrlimiton Unix) - Executor spawns a Sandbox Worker subprocess, sending a JSON envelope via stdin
- ResourceWatchdog monitors the subprocess for timeout and memory violations
- Inside the subprocess, the Sandbox Worker runs code with restricted builtins and import whitelist
- Results (stdout, variables, errors) are serialized as JSON and sent back via stdout
Project Structure
py-sandbox-mcp/
├── LICENSE
├── README.md
├── pyproject.toml
├── src/
│ └── py_sandbox/
│ ├── __init__.py # Package entry, exports execute() and ExecutionResult
│ ├── ast_validator.py # AST-based security gate
│ ├── builtin_policy.py # Safe builtins dict and import whitelist
│ ├── cli.py # CLI entry point (py-sandbox command)
│ ├── config.py # Default limits and blocked/allowed lists
│ ├── executor.py # Orchestrator: validation → spawn → capture
│ ├── platform_utils.py # Windows Job Object / Unix setrlimit + watchdog
│ ├── sandbox_worker.py # Subprocess worker: restricted exec environment
│ └── server.py # MCP server (py-sandbox-mcp command)
├── tests/
│ ├── __init__.py
│ ├── test_ast_validator.py
│ ├── test_builtin_policy.py
│ └── test_executor.py
Running Tests
uv run pytest
License
MIT