Add microVM backend scaffolding with fail-closed admission#276
Merged
Conversation
backend="microvm" previously raised a flat, generic NotImplementedError from the shared backend guard. Replace it with a dedicated, honest fail-closed path so the strongest boundary PyIsolate targets has real groundwork and diagnostics. New pyisolate/runtime/microvm.py provides the parts that do not need a running hypervisor to be useful or testable: - capability detection: is a supported VMM (Firecracker, Cloud Hypervisor, QEMU) on PATH and is /dev/kvm readable+writable (detect_microvm_support); - fail-closed admission: require_microvm_support raises MicroVMUnavailable (a SandboxError) naming every missing prerequisite; - machine-config generation: MicroVMConfig turns a sandbox's memory limit into the full-VM JSON a Firecracker-style VMM consumes, with validation. Supervisor.spawn routes backend="microvm" to _spawn_microvm, which probes the host and either refuses with the diagnostic above, or -- when the host is capable -- refuses with a precise NotImplementedError noting the guest launcher and vsock transport are still pending. It never downgrades to a weaker boundary, matching the threat model. The module-level spawn() guard lets microVM through to this path instead of the generic error. Docs (README, threat model) updated. Two existing tests that asserted the old generic error are updated to the fail-closed contract. New tests/test_microvm.py covers detection, admission, and config generation without needing KVM. Full suite: 491 passed, 6 skipped. pylint 9.57; black/isort/flake8/mypy clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PbbJc7Ntj159D9LNGevwC2
This was referenced Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
backend="microvm"previously raised a flat, genericNotImplementedErrorfrom the shared backend guard. This replaces it with a dedicated, honest fail-closed path so the strongest boundary PyIsolate targets has real groundwork and diagnostics — without pretending to boot a guest it cannot yet boot.What's included
New
pyisolate/runtime/microvm.pyprovides the parts that don't need a running hypervisor to be useful or testable:detect_microvm_support) — is a supported VMM (Firecracker, Cloud Hypervisor, QEMU) onPATH, and is/dev/kvmreadable+writable? Collects the blocking reasons.require_microvm_support) — raisesMicroVMUnavailable(aSandboxError) naming every missing prerequisite. microVM has no weaker mode to degrade to: either a hardware-VM boundary is possible or the request is refused.MicroVMConfig) — turns a sandbox's memory limit into the full-VM JSON a Firecracker-style VMM consumes (boot-source/drives/machine-config/vsock), with validation (vcpus ≥ 1, mem ≥ 1 MiB, guest CID ≥ 3).Supervisor.spawnroutesbackend="microvm"to_spawn_microvm, which probes the host and either refuses with the diagnostic above, or — when the host is capable — refuses with a preciseNotImplementedErrornoting the guest launcher and vsock transport are still pending. The module-levelspawn()guard lets microVM through to this path instead of the generic error.Explicitly out of scope
Booting a guest and carrying the cell protocol over vsock — that launcher is the next increment and needs KVM, which CI hosts lack. This PR is the detection + config + fail-closed admission layer, mirroring how the process backend landed transport-first (#267) before its confinement layers.
Docs & tests
README and the threat model are updated to describe the probe-and-fail-closed behavior. Two existing tests that asserted the old generic error are updated to the fail-closed contract. New
tests/test_microvm.pycovers detection, admission, and config generation without needing KVM (host capability is monkeypatched both ways).Full suite: 491 passed, 6 skipped. pylint 9.57 (gate 8.0); black/isort/flake8/mypy clean.
🤖 Generated with Claude Code
Generated by Claude Code