More
Performance
Every run builds a brand-new box, checks it, runs the program, and removes it. On an M-series Mac that whole cycle takes about a fifth of a second.
Measured#
20 runs of the program pass in the default image, and 10 in data, each in a fresh box, with the VM already running. Recorded 21 October 2026 with python tools/bench.py on the machine PyBox was built on, after the review fixes.
| Phase | What happens | stdlib, median | data, median |
|---|---|---|---|
| Admission and tidy-up | Take the lock, list this installation's boxes | 0.012 s | 0.011 s |
| Create | Build the box from its image | 0.024 s | 0.022 s |
| Read back | Ask the engine what it built and check every setting | 0.012 s | 0.012 s |
| Arm the watcher | Start the kernel watcher inside the VM | 0.009 s | 0.009 s |
| Run | Start the box, Python starts, the program runs, the box exits | 0.067 s | 0.192 s |
| Remove | Remove the box and confirm it's gone | 0.067 s | 0.065 s |
| Total | From the call to the receipt | 0.204 s (0.177–0.391) | 0.321 s (0.315–0.341) |
The data run includes the 0.12 s pause for a final reading. Starting the VM takes about 20 seconds and happens once, with pybox vm start.
What made it faster#
The first measurement (M9) took 0.316 s per run, and almost half of that was arming the kernel watcher: 0.146 s. Nearly all of it went to starting colima and Lima's helper programs before the SSH connection, which Lima already keeps open. PyBox now runs /usr/bin/ssh over that open connection itself, which takes 4–9 ms. It reads only four values from Lima's SSH settings (user, port, key and connection socket) and checks each one against what this installation expects. If any check fails, it falls back to colima ssh. The receipt records which way the watcher was reached (configured.watcher_transport).
Why there's no pool of ready boxes#
Keeping boxes pre-built would save a few hundredths of a second per run. It would also mean a box could exist before you asked for it, with settings checked at some earlier time, and possibly reused. "Fresh every time, checked just before it runs" is the point of PyBox. At about 0.2 s per run, giving that up isn't worth it, so PyBox doesn't do it.
Reproduce it#
$ pybox vm start $ python tools/bench.py --runs 20 $ python tools/bench.py --runs 10 --image data
Each benchmark run is a real sealed run, so the usual rule applies: one run at a time per installation.