Command reference

Polythene exposes two Cyclopts commands. Both commands accept the optional --store argument to override the root filesystem directory (defaults to /var/tmp/polythene).

Before running commands, decide how they interact with your host. Polythene provides a single interface but adapts to the available tooling:

• Codex sandbox – You run as root without container engines. The polythene pull command still uses Podman inside the sandbox because Codex maintains the binary on disk, and polythene exec falls back to bwrap, proot, or a privileged chroot.
• GitHub runners – You run as an unprivileged user with Podman available. The CLI exports images in the same way but typically selects bwrap for execution, providing equivalent isolation to the Codex workflow.

In both environments the exported root filesystem is disposable, enabling repeatable system-level tests without polluting the host.

uv run polythene pull docker.io/library/busybox:latest
# or
python -m polythene pull docker.io/library/busybox:latest

The pull command:

• ensures the store directory exists,
• calls podman to pull the requested container image,
• exports the image into a UUID-named root filesystem directory, and
• prints the generated UUID to stdout for later reuse.

Podman must be installed and available on PATH. When the POLYTHENE_VERBOSE variable is set, the command also prints progress messages to stderr.

uv run polythene exec <uuid> -- uname -a
# or
python -m polythene exec <uuid> -- uname -a

Replace <uuid> with the value returned by a previous polythene pull call. The exec command runs a user supplied program inside the exported root filesystem. It picks the first available execution backend in the following order:

1. bwrap
2. proot
3. A privileged chroot

Each backend receives the prepared filesystem as its root and blocks network access. If none of the backends is available, the command fails with an error message detailing the missing tooling.

When a specific backend is preferable, pass --isolation <backend> (or the equivalent --isolation=<backend> form) to reorder the probing sequence. GitHub runners lack user namespace support for bwrap, and specifying --isolation proot avoids the noisy permission errors emitted by bubblewrap before proot succeeds.

Because the same UUID works across hosts, you can prepare an image on Codex and reuse it on CI:

uv run polythene pull registry.example.invalid/tools:latest
uv run polythene exec <uuid> -- make -C /workspace/tests system

The exec invocation will select the available backend on each host while the commands run unchanged.