Skip to content
LlaberryPublic

About

Authorized to be moved to https://github.com/Azathothas/podbox

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

podbox

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.

State

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.

Building

⭐ 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 INTERP

The 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

The gate

./scripts/check-todo.py   # nineteen checks. Must exit 0 at every commit
./scripts/plant.sh        # break each one on purpose, assert it goes red

The 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.

Licence

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.

About

Authorized to be moved to https://github.com/Azathothas/podbox

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages