Concepts

How it works

Watch one real, recorded run from start to finish. Each step is also written out below, with links to the details.

The run shown was recorded on 19 October 2026. Times inside the run are slowed down so you can follow them; the real run took 0.054 seconds.

The ten steps#

1. You hand PyBox a program. The whole program travels on standard input. It never becomes part of a command line, and it can't choose any settings.
2. It makes sure it's the only run, and tidies up. A lock lets one run (or cleanup) in at a time. Before building anything, PyBox removes this installation's expired, stopped leftover boxes, and nothing else. How cleanup decides.
3. It writes down what it's about to build, before building it. A small private note records the run's identity. If PyBox crashes halfway, the next run reads the note and knows a box might exist.
4. It builds a fresh, sealed box. A brand-new Linux container from one pinned image: no folders from your Mac, no network, a read-only system, 128 MB of memory, 32 processes, half a CPU core. The sealed box.
5. It reads the settings back and checks every one. PyBox asks the container engine what it actually created and compares it with the fixed policy. Any difference and the program never starts.
6. A watcher outside the box gets ready. A small, trusted reader inside the VM, but outside the box, starts sampling the box's memory, process and CPU counters straight from the Linux kernel. It only reads. It never stops or removes anything.
7. The program runs, and two clocks start. PyBox's own 2-second deadline on your Mac, and a 3-second timer inside the box that runs as the box's very first process. Why two clocks.
8. It finishes, and PyBox asks the engine what happened. The exit code comes from the engine's record, not from anything the program printed. The program's output is kept, but labelled untrusted.
9. The box is removed, and PyBox checks it's really gone. Remove, then look again for that exact box. Only then is the note from step 3 closed.
10. You get the receipt. What was asked for, what was seen, what the program said, and what isn't known. Reading a receipt.

What if PyBox itself crashes?#

Steps 8 and 9 need PyBox to be alive. If something kills PyBox mid-run, nothing on your Mac is left to stop the program, so the timer inside the box does it. In a recorded test, PyBox was force-killed about 0.1 seconds into an 8-second sleep. The timer still ended the program at 3.03 seconds, with no help from PyBox.

The stopped, empty box stays behind. It holds no running code, only its record. The next PyBox run (or pybox cleanup) removes it once it has expired, about two minutes after it was created.

Watch it offline or share it#

The walkthrough is also available as a video file: how-pybox-works.mp4 (1080p, 87 seconds, with captions and background music).

Checked against the source on 20 October 2026.