PyBox Docs

Getting started

Install and set up

About five minutes, most of it a one-time download. PyBox shows you every step before it changes anything, and never installs software for you.

Before you start#

You needWhyCheck
A Mac with Apple Silicon (M1 or later)The sealed box runs in a lightweight ARM virtual machineuname -m prints arm64
Python 3.11 or newerPyBox uses only the standard library, but needs 3.11's timestamp parsingpython3 --version
Colima and the Docker CLIColima runs the private virtual machine; Docker talks to itbrew install colima docker
About 1 GB of diskThe VM image (~330 MB download) and the pinned Python image—

You don't need Docker Desktop. PyBox uses its own private Colima profile and never touches your existing Docker setup or contexts.

1. Install PyBox#

Terminal
$ pipx install pybox-sandbox
Terminal
$ python3 -m pip install pybox-sandbox
Terminal
$ git clone https://github.com/ctxnn/pybox
$ cd pybox
$ python3 -m pip install .

That gives you the pybox command (pybox --version to check). PyBox has no dependencies. The package is called pybox-sandbox on PyPI because the name pybox was taken; the command is pybox and the Python import is import pybox.

2. Preview the setup#

Terminal
$ pybox setup

This is a dry run. It checks your Mac and lists every folder and file it would create, then explains what would happen next. Nothing changes yet.

Example output (trimmed)
ok        tool /opt/homebrew/bin/docker
ok        tool /opt/homebrew/bin/colima
create    private directory (0700) ~/.pybox/runtime
create    file (0600) ~/.pybox/runtime/colima/_lima/_config/override.yaml
create    file (0600) ~/.pybox/runtime/docker/config.json
…
Then: start the dedicated VM profile 'pybox' once (first run downloads Colima's VM image, ~330 MB),
pull only the pinned image python@sha256:70729b46… for linux/arm64 from Docker Hub,
verify it, and stop the VM. No host folders are shared and no ports are forwarded.

Dry run: nothing was changed. Run `pybox setup --yes` to do this.

3. Build the sealed box#

Terminal
$ pybox setup --yes

PyBox now:

  1. Creates a private folder at ~/.pybox/runtime, readable only by you.
  2. Starts a dedicated virtual machine called pybox, with no shared folders and no forwarded ports.
  3. Downloads exactly one image: a specific Python image, pinned by its fingerprint (digest), so it can't silently change.
  4. Verifies everything, then stops the VM again.

On the build machine, a fresh setup from nothing took 3 min 17 s (21 October 2026), most of it the VM download. Setup prints how long it took and what to run next.

Run it again any time. It never overwrites a file that already exists. If a file differs from what it expects, it stops and tells you which one.

Optional: numpy and pandas#

Terminal
$ pybox setup --yes --with data

Builds the data image from hash-locked wheels, in about 30 seconds. You can do it during the first setup or any time later.

4. Check it#

Terminal
$ pybox doctor
Example output with the VM stopped
ok   platform
ok   docker       /opt/homebrew/Cellar/docker/…/bin/docker
ok   colima       /opt/homebrew/Cellar/colima/…/bin/colima
ok   runtime
--   vm           Stopped (start it with: pybox vm start)
--   engine       dedicated VM is not running (start it with: pybox vm start; check: pybox doctor)
--   image data   not installed (pybox setup --yes --with data)

doctor is read-only. Every line that isn't ready says what to run next. The engine and image checks can only pass while the VM is running. Add --json for a machine-readable report.

Uninstall#

There is no pybox uninstall yet. To remove everything PyBox created, stop the VM, delete its profile, then delete the folder:

Terminal
$ pybox vm stop
$ COLIMA_HOME=~/.pybox/runtime/colima LIMA_HOME=~/.pybox/runtime/colima/_lima colima delete pybox
$ rm -rf ~/.pybox
$ python3 -m pip uninstall pybox

The last two commands are permanent. They delete PyBox's VM disk and its record of past runs. They don't touch your other Colima profiles or Docker setup.

Next: your first sealed run.

Checked against the source on 21 October 2026.

esc