More
Reference
Every number in one place, checked against the source. For explanations, follow the links.
The box#
| Setting | stdlib (default) | data |
|---|
| Image | python@sha256:70729b46c69b4f1e97c4822c1af3df53a1476cf5ddc6c087c0c10bc3a5678c2f, linux/arm64, never pulled at run time | Built once by pybox setup --with data from that image plus hash-locked numpy 2.5.4, pandas 3.0.6, matplotlib 3.11.2 and their dependencies (pybox/images/data.lock). Your own images (pybox image build) get the same limits. Each is checked against its recorded image ID and recipe SHA-256 before every run |
| Memory (and memory + swap) | 128 MiB | 512 MiB |
| Processes | 32 | 64 |
| CPU | 0.5 core (a rate: about 1 CPU-second in 2 s) | 1 core |
| First process | timeout -s KILL <timeout_s + 1> python -I -B -u -; for runs that move files, … python -I -B -u -c <fixed helper> |
| User | 10000:10000, all capabilities dropped, no-new-privileges, default seccomp |
| Files | Read-only root; /tmp 16 MiB (64 MiB for runs that move files), no executables, no device files; no mounts |
| Network | None |
| Open files | 128 |
| Logs | Engine logging disabled |
Time#
| Budget | Value |
|---|
| Mac deadline | up to 30 s (default 2) |
| Box timer | Mac deadline + 1 s |
| Create / start / inspect / query / stop / remove | 5 / the run's deadline (at least 2) / 2 / 2 / 2 / 3 s |
| Whole cleanup | 15 s (one retry after an interruption gets another 15 s) |
| Box expiry label | 120 s after the run's identity is created |
| Settling an unconfirmed run | allowed from expiry + 60 s |
| Kernel watcher | must be ready within 1 s; 64 samples, 0.05 s apart for the first second, then spread over a longer run; runs at most the deadline + 4 s (at least 6 s); reached by checked direct ssh, or colima ssh as a fallback |
| Final-reading pause (opt-in runs) | 0.12 s, or one sampling gap plus 0.07 s above 2 s; never past the deadline |
| MCP supervisor | 45 s at a 2 s ceiling; above that, the engine's worst case plus 5 s |
Sizes#
| What | CLI and Python | MCP |
|---|
| Program source | 65,536 bytes | 65,536 bytes |
| Output kept per stream | 1–65,536 bytes (default 65,536) | 1–8,192 bytes (default 4,096) |
| Files in | 64 files, 8 MiB in total | 16 files, 256 KiB in total |
| Files back | 64 files, 8 MiB in total | Listed in full; 48 KiB of contents |
| Receipt delivered | — | 64 KiB (output trimmed and flagged to fit) |
| Incoming message / response | — | 512 KiB / 256 KiB |
| Calls / messages per session | — | 32 / 256 |
Receipt layout#
| Key | Contents |
|---|
schema_version | 1 |
identity, container_id, submission.source_sha256 | Which run, which box, which program |
configured | What was asked for |
observed | policy_verified_before_start, effective_policy, engine_state, resources, termination |
capture | stdout, stderr, output_complete, *_truncated: untrusted |
lifecycle | last_phase, cancelled, timeouts, timing |
cleanup | status, removed, reconciliation summary |
clock_domains, unknown | Which clock each time uses; what can't be known |
files | For runs that move files: inputs and outputs (name, bytes, SHA-256), anything skipped, transfer errors. null otherwise |
explanations | Evidence-tagged reasons (codes) |
Files PyBox creates#
| Path | What it is |
|---|
~/.pybox/runtime/ | Everything PyBox owns. Private to you (0700) |
…/colima/ | The private VM profile pybox and its disk |
…/colima/_lima/_config/override.yaml | Turns off port forwarding for this VM |
…/docker/config.json | An anonymous Docker config with no stored credentials |
…/installation.json | This installation's random owner ID, used to label boxes |
…/images.json, …/images.lock | IDs and recipe fingerprints of locally built images (private, written only by setup and pybox image, one at a time) |
…/recipes/NAME.lock | The saved, normalized lock file of each image you built |
…/attempts/ | Notes written before each box is built |
…/lifecycle.lock | Lets one run in at a time |
Requirements#
- macOS on Apple Silicon (arm64). Anything else is refused.
- Python 3.11 or newer. On older versions some timestamps can't be read and labels fall back to
UNKNOWN.
colima and docker from /opt/homebrew/bin or /usr/local/bin only. $PATH is never searched, and the binaries must not be writable by other users.
Source map#
| File | Responsibility |
|---|
pybox/container.py | Paths, guards, rules, the run lifecycle, cleanup |
pybox/runtime_setup.py | setup, vm, doctor |
pybox/_observe.sh, observation.py | The kernel watcher and its strict parser |
pybox/inspection.py | The receipt |
pybox/mcp.py, mcp_policy.py | The MCP server and its limits |
pybox/repair.py, nim.py | The AI repair loop and its model client |
pybox/runner.py | The unsealed learning runner |
Checked against the source on 21 October 2026.