Getting started
Introduction
PyBox runs a Python program you don't trust inside a sealed, throwaway box on your Mac, then hands you a receipt: what the program did, what it printed, and what PyBox could not confirm.
The problem#
Someone sends you a script. An AI assistant writes some code. A tutorial says "just run this". The code might be fine. It might also read your files, phone home, or never stop. Reading it carefully helps, but you can't always tell by looking.
The usual answer is "run it somewhere safe". That raises two more questions that rarely get a straight answer: how safe, and how do you know what actually happened in there?
What PyBox does#
- Builds a fresh, sealed box. Every run gets a brand-new Linux container inside a private virtual machine on your Mac. The program can't see your files, can't reach the internet, gets 128 MB of memory and half a CPU core, and is stopped after 2 seconds. When a job needs more, you can ask for numpy and pandas, up to 30 seconds, and copies of files in and out, all shown on the receipt.
- Checks the seal before starting. PyBox reads the box's settings back from the container engine and refuses to start the program if anything differs from the fixed policy.
- Stops the program even if PyBox crashes. A timer inside the box ends the program one second after PyBox's own deadline, so a crashed or killed PyBox can't leave a program running.
- Writes you a receipt. It records what it asked for, what the engine and the Linux kernel actually observed, what the program printed (clearly marked as untrusted), and what it still doesn't know.
- Cleans up, carefully. It removes the box and then confirms it is gone. It never sweeps away anything it can't prove is its own.
Who it's for#
run_python. The program's output always comes back as data, never as instructions.
The curiousWatch a run step by step. PyBox started as a project to learn exactly what happens between "run this" and "here's the result".
What makes it different#
Most tools tell you a program "succeeded" or "failed". PyBox keeps four kinds of fact apart, because mixing them is how people end up trusting the wrong thing:
| Kind of fact | Example | Where it comes from |
|---|---|---|
| What PyBox asked for | 128 MB of memory, no network | PyBox's fixed settings |
| What was actually seen | The program exited with code 0; the kernel counted one out-of-memory kill | The container engine and the Linux kernel |
| What the program said | "all done!" | The program itself, so it's untrusted |
| What isn't known | The exact final memory count | Stated openly, never guessed |
That last row matters. A program can exit with code 0 even though part of it was killed for using too much memory. PyBox has recorded exactly that, and its receipt shows both facts instead of picking one. See the evidence.
Where it stands today#
Research prototype, Apple Silicon Macs only. PyBox has been carefully tested on one machine, with dated, recorded evidence for every claim on this site. The setup that lets anyone build the sealed box on their own Mac has been run from scratch in a fresh installation (21 October 2026, on the same Mac), but not yet on a second Mac. It is not a hosted service, and it isn't approved for running hostile code from the public internet.
Ready? Install PyBox, or watch how a run works first.