Drew Newberry
910d3f09f2
* feat(vm): boot sandboxes from ext4 root disks * feat(vm): boot sandboxes with writable overlay disk * fix(sandbox): improve sandbox provisioning behavior * fix(vm): repair sandbox image provisioning * fix(vm): clean up rebase fallout * perf(vm): cache empty overlay images * perf(vm): skip repeated sandbox ownership repair * fix(vm): address lifecycle review issues * fix(vm): repair gateway vm startup * wip
VM Driver Runtime
Status: Experimental. VM support is under active development and may change.
This directory owns the pinned runtime inputs for openshell-driver-vm:
runtime/
pins.env
kernel/
openshell.kconfig
openshell-driver-vm embeds libkrun, libkrunfw, gvproxy, umoci for guest-side
OCI image unpacking, and the bundled openshell-sandbox supervisor.
Why
The stock libkrunfw kernel does not include the bridge, netfilter,
conntrack, cgroup, seccomp, and Landlock features the sandbox supervisor needs
inside each microVM. kernel/openshell.kconfig extends the libkrunfw kernel so
VM sandboxes can run the same supervisor enforcement path as other backends.
Build Scripts
| Script | Platform | Purpose |
|---|---|---|
tasks/scripts/vm/build-libkrun.sh |
Linux | Builds libkrunfw and libkrun from source with the custom kernel config |
tasks/scripts/vm/build-libkrun-macos.sh |
macOS | Builds portable libkrunfw and libkrun from a prebuilt kernel.c |
tasks/scripts/vm/package-vm-runtime.sh |
Any | Packages vm-runtime-<platform>.tar.zst with libraries, gvproxy, umoci, and provenance |
tasks/scripts/vm/download-kernel-runtime.sh |
Any | Downloads runtime tarballs from the vm-runtime release and stages compressed files |
Local Flow
# Download the current pre-built runtime and stage compressed artifacts
mise run vm:setup
# Build the bundled guest supervisor
mise run vm:supervisor
# Build the gateway and VM driver with embedded runtime artifacts
OPENSHELL_VM_RUNTIME_COMPRESSED_DIR=$PWD/target/vm-runtime-compressed \
cargo build -p openshell-server -p openshell-driver-vm
Use FROM_SOURCE=1 mise run vm:setup to build the runtime from source instead
of downloading vm-runtime-<platform>.tar.zst.
CI Ownership
release-vm-kernel.yml is the on-demand producer for:
vm-runtime-linux-aarch64.tar.zstvm-runtime-linux-x86_64.tar.zstvm-runtime-darwin-aarch64.tar.zst
Those artifacts stay on the rolling vm-runtime release. Normal dev and v*
release workflows download them, embed them into openshell-driver-vm, and
publish the driver binary next to openshell-gateway.
Provenance
package-vm-runtime.sh writes provenance.json into each runtime tarball with
the platform, libkrunfw commit, kernel version, gvproxy and umoci versions,
GitHub SHA, and build time. The driver logs this metadata when it extracts and
loads a runtime bundle.
The release workflow also publishes GitHub artifact attestations for each runtime tarball. Verify a downloaded runtime with:
gh attestation verify vm-runtime-linux-x86_64.tar.zst -R NVIDIA/OpenShell