PyBox

Run Python you don't trust in a fresh, sealed box on your Mac — and get a receipt that says how it knows what happened.

You give PyBox a program. It runs it once in a brand-new Linux container inside a private VM: no network, no access to your files, a read-only system, strict memory, CPU and process limits. Then it removes the box and hands you a receipt that keeps four kinds of fact apart: what was configured, what the engine and kernel observed, what the program printed, and what is still unknown.

When a job needs more, you ask for it on that run, and the receipt shows it: numpy, pandas and matplotlib (the data image), your own pinned packages, up to 30 seconds, and copies of files in and out. The same engine works from the command line, from Python, as an MCP tool for AI agents (claude mcp add pybox -- pybox mcp), and in a bounded AI repair loop where the model can only propose code.

Quickstart

Requirements: macOS on Apple Silicon, Python 3.11 or newer, and brew install colima docker. PyBox has no Python dependencies and never installs software for you.

git clone https://github.com/ctxnn/pybox && cd pybox
python3 -m pip install .

From PyPI, once 0.3.0 is released: pipx install pybox-sandbox (the name pybox was taken). Either way the command is pybox and the Python import is import pybox.

Set up once

pybox setup              # dry run: shows every folder, file and download first
pybox setup --yes        # about 3–5 minutes, mostly the one-time VM download
pybox setup --yes --with data   # optional: numpy, pandas, matplotlib, about 30 s
pybox doctor             # read-only check; says what to run next

Setup creates a private ~/.pybox/runtime, starts a dedicated Colima profile pybox (no host folders, no forwarded ports), pulls only the pinned Python image by digest, verifies it, and stops the VM. It never overwrites a file. The data image is built in the VM from hash-locked wheels; it is the only time a PyBox container has the network.

Run things

pybox vm start
echo 'print(6*7)' | pybox exec -
pybox exec report.py --input sales.csv --output results/
pybox exec analysis.py --image data --timeout 20
pybox image build tools --lock tools.lock   # your own packages, from uv pip compile --generate-hashes
pybox vm stop

pybox exec prints the program's output, then a short receipt (to stderr):

42

PyBox receipt · run 5319e024 · image stdlib · 0.166 s of 2 s

From the container engine  checked before start, read back after
  Exit code             0 (ended by itself)
  Settings checked      yes, before the program started
  Mac folders shared    none
  Network               none
  Limits                128 MiB · 32 processes · 0.5 CPU · 2 s (+1 s box timer)
  Box                   removed and confirmed gone

From the Linux kernel  sampled while it ran, from outside the box
  Memory peak           2.5 MiB of 128 MiB
  Processes peak        6 of 32
  CPU throttled         0 periods

From the program  untrusted: a program can print or write anything
  Printed               3 bytes on stdout, 0 bytes on stderr

Not known  PyBox says so instead of guessing
                        final counters (the box can vanish between readings) · exact clock alignment

--json prints the full versioned record instead. A complete fresh-box run takes about 0.2 s once the VM is running (performance). Returned files are written all at once, never overwrite anything, and are marked like downloads so macOS checks them when opened.

With an AI agent

claude mcp add pybox -- pybox mcp --images stdlib,data --max-timeout 30

The agent gets one tool, run_python, with optional image, files and return_files. You set the ceilings; the agent can only ask for less. Program output and returned files come back as data inside the result, never as protocol messages. Tested with PyBox's own MCP client, Claude Code and Cursor's command-line agent; not yet with Claude Desktop (details).

From Python

from pybox import run_container

result = run_container(open("report.py").read(), image="data", timeout_s=10,
                       inputs=[("sales.csv", open("sales.csv", "rb").read())],
                       collect_outputs=True)
print(result.record["cleanup"]["status"], [name for name, _ in result.output_files])

Tests

python3 -B -W error::ResourceWarning -m unittest discover -s tests

Expect Ran 209 tests … OK. They mock the engine and never start the VM.

What PyBox promises — and what it does not

Exit code 137 alone never establishes a cause. PyBox labels a termination only when its own recorded KILL or the timer's timing supports it, and otherwise says so.

Documentation

Status

M1–M6 are complete and locally qualified. M7 (documentation, site, review) is delivered. M8 (installable, portable paths, setup / vm / doctor) is implemented. M9 (the data image, files in and out, runs up to 30 s, pybox exec with a readable receipt, configurable MCP, PyPI-ready packaging, benchmarks) is implemented, unit-tested (198 tests) and checked live in a throwaway installation; see M9 results. M10 (matplotlib, your own images, final readings, a 15× faster watcher, Cursor tests, an independent security review with every finding resolved) is done; see M10 results. Not done yet: a second Mac, Claude Desktop, a PyPI release, the Homebrew tap. Committed locally on branch m9-useful-for-real-work; not pushed.

Contributing, security and changes

• CONTRIBUTING.md: set up, run the tests, test against a real VM safely.
• SECURITY.md: report a vulnerability privately; what's in scope.
• CHANGELOG.md: what's in each release.

License

Apache License 2.0.