More
FAQ
Short, straight answers.
Is it safe to run anything in PyBox?#
It's much safer than running untrusted code directly, and every protection was tested. But no tool can promise safety against every possible attack, and PyBox doesn't. It's a carefully tested research prototype, not a certified sandbox. Don't use it to run hostile code from strangers on the internet on a machine you care about.
Does it need the internet?#
Only during setup: pybox setup --yes downloads the VM image and the pinned Python image, and --with data downloads numpy and pandas once. After that, running programs needs no internet, and programs in the box can't reach it.
Can the program see my files?#
No folders from your Mac are shared with the box, and PyBox checks that before every run. In a recorded test, a program trying to open a file that exists on the Mac got "no such file". If you want a program to read a file, pass a copy with --input; your original is only read. See files in and out.
What happens if my Mac sleeps mid-run?#
Sleep pauses the VM, and time inside the box pauses with it. PyBox's deadlines weren't designed or tested around sleep, so treat a run that spanned a sleep with suspicion and read its receipt. The timers are practical limits, not real-time guarantees.
Does it work on Windows, Linux or Intel Macs?#
Not yet. Only macOS on Apple Silicon. Everywhere else, PyBox refuses to start the sealed box rather than run without it.
Can I use numpy or pandas, or install packages?#
numpy, pandas and matplotlib, yes: build the data image once and pass --image data. For other packages, build your own image from a lock file with pinned versions and hashes. Installing packages during a run, no. Every run gets a fresh box with no network and a read-only system, and nothing carries over between runs. That's what makes each receipt independent.
How long can a program run?#
2 seconds by default, up to 30 if you ask with --timeout. The default stays short so a forgotten loop costs you two seconds, not thirty. For AI agents, the person who configures the server picks the ceiling.
How fast is it?#
A whole run, from building a fresh box to removing it, takes about a fifth of a second once the VM is running. See Performance.
Can I install it with pip?#
Yes: pipx install pybox-sandbox. (The name pybox was already taken on PyPI.) The command is still pybox, and the Python import is still import pybox. See Install.
Is PyBox a hosted service?#
No. It runs entirely on your own Mac. There's no account, no server and no telemetry.
Why does every receipt list "unknowns"?#
Because some things genuinely can't be measured exactly, like the final memory reading of a box that vanished between two readings. PyBox would rather tell you that than invent a number.
Who made it?#
PyBox began as a learning project: what actually happens between "run this" and "here's the result"? Each step was built, tested on real hardware, and written up. The full lab notebook is in the repository's LEARNING.md.