Engineering guide¶

Run commands from the repository root. mise tasks ls lists public tasks; mise run ci runs the local check sequence, and mise run ci -- check "test pvisor-core" runs selected tasks in order and stops on failure. Internal tasks stay callable but are hidden from the default help.

Install mise 2026.8.5 or newer, then prepare the development environment:

mise trust
mise install --locked
mise run setup
mise run doctor

mise.toml pins Rust (including rustfmt and Clippy), Python 3.12, uv, Ruff, actionlint, jq, Zig, nextest and cargo-zigbuild. setup installs the current architecture's Linux musl guest target and syncs development dependencies into .venv from uv.lock; it neither installs pVisor itself nor builds firmware. The Python product still supports 3.10+; development tools use 3.12.

CI and wheel builds use mise 2026.10.18 with the committed tool versions and lockfiles. For compatible local tools already on PATH, set disable_tools = ["python", "uv", "jq"] in the [settings] table of the ignored mise.local.toml; disabled tools must be provided by the caller. Python development tasks require 3.12 or newer, and UV_PYTHON falls back to python3 when Python is disabled. Select other mise-managed versions in that file's [tools] table and check them with mise ls --current. Release builds and recorded benchmark comparisons use a clean checkout without personal overrides or disabled tools.

mise run selects the project tools and environment without shell activation. For direct Cargo or Python commands, use mise exec -- cargo … / mise exec -- python3 …, or activate your shell following mise's shell setup instructions. Separate task arguments from mise with --; Rust tests use a second -- between package names and nextest options, for example mise run test -- core -- --offline.

Platform package managers still provide native dependencies: Linux build libraries, FUSE, KVM and cgroup permissions, or macOS Xcode Command Line Tools, LLVM/GNU tools and macFUSE. See Build environment below and the executor guides. Machine-specific overrides belong in ignored mise.local.toml; keep personal paths and credentials out of shared configuration. Update tool versions in mise.toml, use CI's mise 2026.10.18 to run mise lock --platform linux-x64,macos-arm64 and commit mise.lock; after changing Python dependencies, run mise exec -- uv lock and commit uv.lock.

Repository layout and ownership¶

The Cargo workspace has 13 crates organized by product responsibility. Its default member is pvisor-cli. Python pvisor/ is an installable version marker, not a launcher or runtime implementation. Wheels install native executable scripts directly into the environment's bin directory; the old Python launcher and its binary override are obsolete.

Direct normal workspace dependencies (including target-specific edges; names below omit the pvisor- prefix):

cli ──> pvisor, core, journal, replay, overlaynet, overlay-core, vm
pvisor ──> core, journal, overlaynet, overlayfs, overlay-core, guest, vm
cli --features gateway ──> gateway, pvisor/gateway
pvisor --features gateway ──> gateway
vm ──> overlay-core, guest
daemon ──> pvisor, core, guest
replay ──> core, journal
shim ──> guest, overlay-core
shim --features vm ──> vm, overlaynet, core
gateway ──> core, journal, overlaynet
overlaynet ──> core
overlayfs ──> core, overlay-core
overlay-core ──> core, journal
journal ──> core
core, guest ──> no other workspace crates

pvisor has no CLI or Clap normal dependency; Clap is a development dependency for examples only. The pvisor-replay engine has no normal dependency on pvisor or Clap. The pvisor-tui crate has been removed; its executable name is unchanged.

pVisor source modules¶

The CLI owns arguments/display; the runtime owns execution and durable Jobs. VM, filesystem and network implementations stay in their owning crates. Core defines shared policies and wire DTOs. Jobs and daemon reuse in-process control while retaining their own authentication, admission, storage and confirmed cleanup.

See Core architecture for public interfaces and migration status. Only VM, OverlayFS and Journal currently use a sole api entry. Other crates retain their actual exports; this logical table does not imply unified Rust visibility or stability.

Core implementation boundaries¶

Core defines Operation, Event and shared policies; pvisor implements admission, actual rewrites, Placement and scheduling. Session owns Attempt resources/terminal states; executors execute and return observations; OverlayCore owns file application/recovery. AgentCtl and approval socket I/O remain in pvisor. See Core architecture for ownership and Operation and Event for fields/order.

Core reduction budget¶

CI checks the default runtime and application dependency boundaries before the capture-enabled distribution. scripts/ci/check_core_budget.py rejects the CLI, Gateway, replay, Clap, TUI and terminal dependencies in the normal pvisor closure. The default pvisor-cli application includes the replay engine and integrated TUI, while Gateway remains optional. It records toolchain, runtime/application dependency counts, runtime-closure source lines, public Core declarations and application binary bytes. The dependency count, closure source lines and Core declarations ratchet against a committed baseline (scripts/ci/core-budget.json): any metric above the baseline fails CI, so no absolute caps are hand-maintained in the CI config. A change that intentionally grows the budget regenerates the baseline with mise run update-core-budget in the same commit, keeping the exact delta reviewable; regenerating after a reduction tightens the baseline to reality. The script owns budget/measurement definitions; CI reports contain measured results. Compare on the same platform/toolchain.

Contributor commands¶

mise run test/mise run test-rust accept Cargo package names and aliases pvisor, cli (pvisor-cli), core, control/agentctl (Core compatibility aliases), capture (Gateway) and shim (pvisor-shim). With package arguments, mise run test runs only those Rust tests. CI shards use mise run test-rust without additionally running Python tests.

Runtime-only Rust tests remain in crates/pvisor/tests/. Executable/frontend integration test files, including mixed runtime/command tests, live in crates/pvisor-cli/tests/; mixed files retain their runtime-only cases in pvisor. Native VM and environment-dependent tests keep their existing prerequisites and skip/ignore gates; compile checks do not validate real guests.

Default unittest discovery includes tests/ and benchmark/. Rust tests in pvisor-core verify shared Operation/Overlay contracts. Benchmark tests requiring /proc and Linux rootfs tools run only on Linux.

VM filesystem checks run inside the Linux guest and require root, Python and tar. From the repository run PVISOR_TEST_GUEST_FS_DIRS=/var/tmp:. mise run test-py -- tests/test_vm_filesystem.py to check guest root/workspace filesystems separately. Checks skip without directory configuration; explicitly enabled failures are errors.

For a specific Rust integration test/filter, pass nextest arguments after --, for example mise run test-rust -- pvisor-gateway -- --test llm_fixtures. nextest excludes doctests; use cargo test --doc -p <package> when needed.

CI responsibilities¶

Keep required status CI: any failed, canceled or skipped dependency fails it. Linux Rust tests shard into core/Gateway/pVisor; macOS runs the same package set once. The separate Linux isolation job requires user namespaces/FUSE and cannot skip isolation checks. Filesystem examples/documentation cases share its release build/isolation environment. Network/Gateway examples run separately.

The shared setup action installs the same mise tools and Python development dependencies as local development. Its native-firmware input prepares macOS native firmware tools, and static-musl installs Linux system build libraries; tool versions come from mise.toml. A reusable workflow owns the two-platform wheel matrix, including mise with the same configuration inside manylinux. PR documentation builds do not cancel Pages deployments.

VM guest startup¶

pvisor-guest provides the shared GuestConfig library and the pvisor-guest executable. With pvisor-vm's init-blob feature, crates/pvisor-vm/build.rs uses Rust's rust-lld to build a release Linux musl ELF for the VM architecture. Separate target/pvisor-guest/ avoids competing with the outer Cargo artifact lock. pvisor-vm embeds the ELF as /init.krun, which becomes guest PID 1.

CLI/shim inject /.pvisor-guest.json containing argv, environment, cwd, workspace mounts, limits, optional networking and shim agent arguments. The supervisor initializes guest filesystems/console I/O, mounts the workspace, configures networking, launches the workload directly and reaps children. On exit, it reports the workload exit code using libkrun's private rootfs ioctl 0x7602, then syncs/reboots. Nonzero exit fails the Attempt; normal VM shutdown without a reported code fails with 125.

See Guest init comparison for measurements and scope.

Packaging and names¶

The PyPI distribution uses pvisor-sandbox; the Python import package, installed CLI and runtime Rust crate use pvisor; the application crate is pvisor-cli, and companion crates use pvisor-*; environment variables use PVISOR_*. Wheel names follow pvisor_sandbox-<version>-py3-none-<platform>.whl.

Build environment¶

Use the Rust toolchain pinned in mise.toml, the default LLVM backend and platform linker. mise run setup installs the current architecture's guest target. Rust's bundled linker builds the guest supervisor as a static Linux musl ELF; macOS VM builds do not require Zig.

CARGO_TARGET_DIR selects native build output shared by build/install/smoke/examples/cases. Wheel verification uses a fresh staging directory so old dist/ packages cannot be mistaken for new artifacts. Linux CLI links musl statically and embeds the VM kernel. The mise installation and setup provide Zig, cargo-zigbuild and the Linux musl target. Linux wheels retain manylinux_2_28 for glibc Python installers.

Documentation tasks use an isolated uv environment with the same pinned Zensical as CI; no separate docs virtual environment is required.

See Release process and Reproducible examples for releases/runtime requirements.

The private runtime modules use a libkrun 1.19.3 base with selected upstream backports. See the upstream synchronization ledger for source commits, local adaptations and validation limits; the version number does not imply a complete 1.19.6 or 2.0 upgrade.

VM API boundary¶

pvisor_vm::api is the sole external runtime interface. It declares portable structs and trait signatures with no conditional compilation or method bodies. Private modules implement the contracts; consumers import VmConfiguration, VmRuntime, VmControl and the snapshot/RAM traits they use. Platform services use RuntimeSupport on VmPlatform.

CLI, shim, examples and the init benchmark use this interface. Low-level register/device tests and hardware probes belong inside pvisor-vm. Static kernel extraction/packing lives in crates/pvisor-vm/build_kernel.rs; its existing build environment variables remain compatible. Firmware data ABI and OS FFI remain private. Historical trace/receipt identifiers and benchmark evidence retain their original names.

Run mise run test -- pvisor-vm; macOS signs its test executables with the existing Hypervisor entitlement. Real VM tests require host HVF/KVM access; Linux VM-creation tests require /dev/kvm.