A container runtime for Linux environments that hand a process uid 0 and then refuse almost every operation containers are built on.
The environment is common: AI-agent sandboxes, hardened CI executors, locked
down HPC nodes. A process there holds every capability bit and Seccomp: 2,
and cannot unshare, mount, pivot_root, ptrace, mknod, setuid to a
non-zero id, or chown to an unmapped one. docker on PATH is a podman alias
with no daemon.
podbox answers to docker and podman on PATH, takes the same verbs, flags
and exit codes, and where it cannot honour something it says so in one line.
podbox run works: a command runs inside a pulled and extracted image, the
payload owns stdout, and the exit code is the payload's own. This tree is
milestones M0 to M3 of
TOOL.md section 5:
the probe, then pull and the store, then unpacking a rootfs, then entering
one. The lifecycle verbs (create, start, ps, logs, stop, rm, exec)
exit 125 and say so. The next milestone is M4, the lifecycle.
podbox probe # the rung on stdout, the evidence on stderr, exit 0
podbox probe --json # the same findings, for a harness
podbox probe --rows # every probe, one row each
podbox probe --strict # exit non-zero below the `namespace` rung
podbox probe --cached # serve $store/probe.json where its key still holds
podbox pull alpine:latest
podbox images --format '{{.Digest}}' alpine:latest
podbox tag alpine:latest myalpine:v1
podbox rmi myalpine:v1
podbox image prune -af
podbox inspect alpine:latest
podbox extract alpine:latest # unpack the layers, print the rootfs path
podbox run alpine:latest /bin/echo hi
podbox run --platform linux/arm64 alpine:latest /bin/uname -m⛔ It reports the mode it achieved and never lets a weaker one satisfy a
stronger request. On a machine that hands a process uid 0 and refuses mounts
it selects chroot, prints what that does not provide, and does not pretend to
be a container.
⛔ The digest it prints is the digest docker prints. That parity is M1's
acceptance and experiments/150-image-acquisition.sh is it as one command.
Every blob is verified as it is written, blocks and inodes are checked at
the destination before anything is fetched, and a registry offering only
http:// is a named refusal rather than a downgrade.
⛔ Extraction never restores ownership, and says what it could not apply.
chown to an id the user namespace does not map returns EINVAL, and that is
where four other tools in the corpus stop. podbox extracts ownership-neutrally
and records what the image intended in .meta.jsonl beside the rootfs, keyed by
path. ⚠ That sidecar changes no kernel permission check and is never presented
as though it does.
⛔ An entry that resolves outside the destination is refused and the extraction fails. Including one that traverses a symlink an earlier entry of the same layer created, which is the case a lexical check cannot see. A repaired layer cannot be told from a clean one, so podbox does not repair one.
⭐ It is not one architecture. The workspace compiles for six, the platform
is decided at run time rather than by a build constant, and the store holds one
record per platform of a tag. On a host with binfmt_misc and qemu-user,
podbox run --platform linux/arm64 runs a foreign image. ⚠ powerpc64le does
not build, and the blocker is named in experiments/260-multiarch.sh.
TODO/PROGRESS.md carries the state line, the counts and the work order.
| path | what it is |
|---|---|
TODO/ |
the work. INDEX.md lists every entry, PROGRESS.md carries the order, reference-map.md carries the corpus and its licence determinations |
crates/ |
the workspace of TOOL.md section 4.3. podbox-probe, podbox-image, podbox-extract, podbox-enter and the M0 to M3 verbs of podbox-cli are implemented; the rest are skeletons |
references/ |
the corpus: 30 trees at pinned commits, with their trackers. Tracked, in the tree |
experiments/ |
the reconstruction of the target runtime, seeded from Azathothas/container-research, plus this project's own measurements |
scripts/ |
the gate, the count scripts, the corpus fetcher, the environment bootstrap, and the zig cc wrappers |
docs/ |
the methodology this repository is worked under, copied verbatim from Azathothas/TEMPLATE. Binding, not advisory |
⭐ Working on this repository: read docs/AGENTS.md and
nothing else first. It is the router. It says what to read for the task in
front of you, what this environment does to a session, and what a session owes
at its end. Everything binding is one link away from it.
⭐ One command, and it returns in about a second. It brings the environment up and compiles in the background, and it is idempotent:
./scripts/dev.sh # environment and build, in the BACKGROUND
./scripts/dev.sh status # ready, stale, or failed with the log
./scripts/dev.sh check # what a change passes before it is committed./scripts/common/bootstrap-env.sh is the environment half on its own, and
takes a component list. By hand, the build is:
cargo build --release --target x86_64-unknown-linux-musl
readelf -l target/x86_64-unknown-linux-musl/release/podbox | grep INTERPThe second command prints nothing: the artefact is a single static binary with
no PT_INTERP. The interposer is the one object that is not static, and it
is built separately:
./scripts/build-interpose.sh./scripts/check-todo.py # nineteen checks. Must exit 0 at every commit
./scripts/plant.sh # break each one on purpose, assert it goes redThe reader re-derives every count in TODO/INDEX.md from the rows, asserts that
no status disagrees between the index and its entry, that every reference in
TODO/reference-map.md resolves, that every cited path and line exists and is
tracked by git, and that CI installs the toolchain .cargo/config.toml names.
Both run in CI and both exit non-zero on a disagreement.
⭐ plant.sh is what makes the gate an assertion rather than a decoration.
A check that quietly matches nothing exits 0 exactly like one whose assertions
all passed, and that is the state this repository shipped its first commit in.
0BSD. No attribution clause, no notice retention, no share-alike.
⚠ Vendored code keeps its own licence and its own notices.
THIRD_PARTY.md carries them, and
TODO/reference-map.md carries the determination that
had to be made before each tree was used.