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:

1. AST Validation — Rejects dangerous code patterns before execution
2. Restricted Builtins — Limits available built-in functions inside the sandbox
3. Import Whitelist — Only safe modules (math, json, re, etc.) can be imported
4. Subprocess Isolation — Code runs in a separate process, not the host
5. 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: setrlimit via preexec_fn + watchdog
• MCP Server — Expose run_python tool 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

Loading

Execution Flow

1. CLI or MCP Server receives code to execute
2. Executor validates code through the AST Validator — if rejected, returns error immediately
3. Platform Utils sets up OS-level resource limits (Job Object on Windows, setrlimit on Unix)
4. Executor spawns a Sandbox Worker subprocess, sending a JSON envelope via stdin
5. ResourceWatchdog monitors the subprocess for timeout and memory violations
6. Inside the subprocess, the Sandbox Worker runs code with restricted builtins and import whitelist
7. 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