podvm runs Linux payloads on hosts that can deny namespaces, mounts, chroot, device creation, ownership changes, or ptrace. It takes Docker and Podman commands, selects a mechanism from the host probes, and names that mechanism in its output. Each released binary is static musl.
The runtime has image acquisition, layer extraction, rootfs completion,
payload entry, lifecycle control, interposition, and a machine tier.
The CLI also provides remote and machine SSH commands.
Most mechanisms are shared crates of
PodUtils/podcrates; the code map names them.
The machine tier boots a Linux guest from an OCI image (run --podvm-tier=machine, TODO/machine.md T-1656), and Windows, DOS, and
machine ssh guests.
A Linux guest can have no NIC (--podvm-net none), one channel to a host
socket (--podvm-channel), its run as a bundle on stdin with no host
file of the run (--podvm-sealed, T-1751), and a container engine
(--podvm-engine, T-1780); the incus tier also takes the first two
(T-1779). The limits state each flag.
--podvm-tier also selects incus (an incusd over its REST API,
T-1718; tier = incus in $store/config selects it with no flag,
T-1722), runsc (gVisor, rootless, T-1729), emulate (a static
qemu-user, T-1651) and syscall (each system call through podvm's
handler, T-1657, T-1731). podvm lab plans a network lab in one guest
(T-1662), and the crate podvm-api runs podvm from Rust (T-1745).
Read the architecture for the execution paths. Read the limits before you select a path. The generated source state names the current build inputs. The work record gives current verification and remaining work.
Each release from 0.2.0-beta.25 carries podvm-install.sh. It finds the
binary of your machine, checks it against the pins in the installer, and
puts it into ~/.local/bin (--prefix DIR sets another place). It needs
no root and no compiler. A second run changes nothing. With
--offline podvm-VERSION.tar.gz it needs no network.
curl -fsSLO https://github.com/PodUtils/podvm/releases/download/TAG/podvm-install.sh
sh podvm-install.shEach release after 0.2.0-beta.28 carries SHA256SUMS and its keyless
signature SHA256SUMS.sigstore.json. Where cosign is on PATH, the
installer of such a release checks them before a download. To check the
installer itself by hand before the first run:
curl -fsSLO https://github.com/PodUtils/podvm/releases/download/TAG/SHA256SUMS
curl -fsSLO https://github.com/PodUtils/podvm/releases/download/TAG/SHA256SUMS.sigstore.json
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
--certificate-identity https://github.com/PodUtils/podvm/.github/workflows/nightly.yml@refs/tags/TAG \
--certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMSBy hand: download the binary of your architecture from
the releases, check it
against its .sha256, and put it on PATH:
curl -fLO https://github.com/PodUtils/podvm/releases/download/TAG/podvm-x86_64
curl -fLO https://github.com/PodUtils/podvm/releases/download/TAG/podvm-x86_64.sha256
sha256sum -c podvm-x86_64.sha256
install -m 0755 podvm-x86_64 ~/.local/bin/podvm
podvm version --verboseEach binary is static: it needs no library of the host. The release has
binaries for x86_64, aarch64, armv7, i686, loongarch64, powerpc64le and
riscv64gc; the interposer of the userland rung is in the x86_64 and
aarch64 binaries. podvm run --help and podvm man list each flag, with
the parity of each docker flag.
Open an issue with the bug form. Give the command, the image with its tag, what you expected, and the output of:
podvm version --verbose
podvm system info --format '{{.Version}} {{.Rung}} {{.EnteredRung}} {{.Platform}} {{.Kernel}}'
podvm probeRun the failing command again with --verbose (the banner names the
mechanism that podvm entered) and, for run, with --report report.json,
which records the rung, the exit code and the times of the run.
sh scripts/cloud-setup.sh
export PATH="$HOME/.local/podvm/zig-x86_64-linux-0.16.0:$PATH"
cargo build --release -p podvm-gate
./target/x86_64-unknown-linux-musl/release/podvm-dev build
./target/x86_64-unknown-linux-musl/release/podvm probe
./target/x86_64-unknown-linux-musl/release/podvm run alpine:latest /bin/echo helloscripts/cloud-setup.sh installs zig, the Rust toolchain and the musl
target, and reports the host. The workspace builds static musl binaries
under target/x86_64-unknown-linux-musl/release/.
podvm-dev build builds both interposer objects before the CLI embeds them.
The build status verifies input and output bytes.
For repository work, read AGENTS.md first.
podvm-dev session reports the host, and podvm-dev check runs the
complete Linux check (the gate).
The Windows lane on wsl-toolkit is parked. Container procedures keep its steps.
podvm probe
podvm doctor
podvm run alpine:latest /bin/echo hello
podvm manThe probe measures this host. A run is quiet; --verbose prints the
banner, which names the selected mechanism. inspect and system info
report runtime state, and --report FILE writes one JSON document of the
run. Each run with --name leaves a record that ps -a lists;
podvm container prune removes each exited record and its tree.
A chroot changes path resolution. The namespace path creates a mount namespace
and private temporary filesystem. It does not create user, PID, or network isolation.
Where chroot is denied, the userland path enters a dynamic payload through the image loader.
A static x86_64 payload there runs on the native-static path: podvm resolves each
path of its system calls in the image (Syscall User Dispatch, TODO/enter.md T-1652).
Under --unsafe-host-paths it runs from a memfd instead.
Read the named refusal when a required mechanism is absent.
The machine tier runs a disposable disk guest through an emulator
(qemu-system-x86_64; KVM where /dev/kvm opens, else TCG). A host with
no QEMU needs no install: podvm fetches a pinned static QEMU 9.2.0 and its
firmware (54 MiB) into its store on the first run, and a QEMU of the host
wins where it is present. podvm pull windows:NAME fetches a medium of
the catalog from its vendor URL and checks its pinned sha256; podvm stores
no Windows image of its own.
podvm run windows:dos ver
podvm run windows:validationos ver
podvm pull windows:2025
podvm run windows:2025 ver
podvm run -d --name dos1 windows:dos
podvm ps
podvm stop dos1
podvm rm dos1
podvm windows doctor
podvm imagespodvm pull windows:2025 (also 11 and 10) installs Windows from its
setup ISO under KVM into a golden image, with one line for each phase; the
password of the user podvm is in a file of mode 0600 beside the image.
Under KVM on a hosted runner, windows:2025 installs in about 9 min and
windows:11 in 11 to 13 min (TODO/machine.md T-1867).
The first run of windows:validationos provisions it one time. podvm images lists the Windows names that the store holds, and podvm rmi windows:NAME removes their files. The operator accepts the terms of each
medium.
A run uses a fresh overlay and a mailbox for command output and exit status.
The guest task records proof per accelerator and guest flavor.
podvm remote ssh --help
podvm machine ssh --helpThe remote commands use the node, operator, and proxy helper executables.
Place compatible helpers beside podvm, or on PATH as podvm-ssh-NAME.
A source workspace build produces them. Read the SSH limits
before you use a downloaded standalone binary for remote SSH.
The release workflow also packages all four helpers in an archive for each architecture. Keep the CLI and helpers from the same release in one directory. Use the archive's licence directory with the distributed executables. The archive does not include an external SSH server. The server endpoint also needs the SSH server named by its configuration.
Select a verified tag and architecture from the release assets. From this checkout, verify the selected binary and helper archive:
sh scripts/verify-release.sh TAG ARCH binary
sh scripts/verify-release.sh TAG ARCH sshBinary podvm-verify owns that verification, and the two lines above
are an exec shim.
The verifier requires gh and cosign.
It checks the tag's workflow identity.
v0.1.0-beta.12 is the last podbox release, and v0.2.0-beta.2 is the first podvm release.
The tags v0.1.0-beta.13 and v0.2.0-beta.1 have no release, because their builds failed.
Tags up to v0.1.0-beta.13 keep the podbox identity: their releases carry podbox-* assets and are signed by the nightly workflow of Azathothas/podbox, and the verifier checks those tags against that identity.
Each later tag carries the podvm identity, and its release has podvm-* assets; podvm-verify decides the identity from the tag.
Azathothas/podbox redirects to this repository, so nobody may create a new repository of that name: it would break the redirect and the old identity with it.
| Page | Purpose |
|---|---|
| AGENTS.md | Session entry point and task routing |
| HUMAN.md | Operator procedure |
| Architecture | Execution paths and data boundaries |
| Code map | Source ownership |
| Limits | Current constraints and proof gaps |
| Findings | Defects of tools and host traits, with the host of each row |
| TODO index | Tasks and derived counts |
| Experiments | Scripts and result captures |
| Security | Trust boundaries |
| Third-party notice | Licenses and carried material |
Read the router and live work record. Work on main.
Update the affected task in the same change.
Run the full gate before commit and authorized publication.
The review checklist defines review evidence.
podvm uses 0BSD. Carried material retains its own terms.