docs(spec-minvmd-linux-kvm): Linux host support for minvmd (KVM backend + vsock bridge) - #399
Merged
Merged
Conversation
Tracks tracking issue #397. Three demoable units: 1. Un-gate libkrun from macOS — build and link on Linux 2. VMM child on Linux — KVM boot, READY marker, UDS↔vsock bridge 3. Linux e2e tests and latency benchmark Resolves the selection-surface open question by deferring auto-spawn on Linux to a follow-up under #396; VM isolation on Linux requires explicitly running `minvmd run --detach`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
📝 WalkthroughWalkthroughAdds a new specification document defining the scope, goals, and three units of work to enable minvmd on Linux with a KVM backend via libkrun, including build un-gating, functional runtime implementation, testing infrastructure, design considerations, and an explicit verification matrix. Changesminvmd Linux KVM Specification
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md`:
- Around line 238-244: The CI spec's Linux KVM job only sets MINVMD_E2E=1 but
does not provide the kernel/rootfs/initramfs inputs the gated tests require;
update the job description to wire the kernel, rootfs and initramfs environment
variables (the same kernel/rootfs/initramfs env names used by the verification
matrix) alongside MINVMD_E2E so the e2e run can materialize kernel + rootfs +
initramfs and execute cargo test -p minvmd -- --include-ignored; ensure the spec
text names the exact env vars (e.g., the kernel/rootfs/initramfs env identifiers
referenced in the matrix) and documents their expected sources/values for the
Linux KVM job.
- Line 388: The table row currently assigns the `minvmd boot --foreground`
smoke-test to R2.3 but R2.3 corresponds to the `cmd/run.rs` item; update the
unit ID to R2.2 so the boot smoke-test correctly maps to the boot work item
(change R2.3 → R2.2 for the row containing `MINVMD_E2E=1` + env vars and `minvmd
boot --foreground`), and confirm any related traceability references referencing
`cmd/run.rs` vs boot are consistent.
- Around line 122-128: Update the R1.1 doc entry to show the rpath linker arg
includes a directory (use `-Wl,-rpath,<dir>`) and mention the Linux default
prefix `/usr` with the `LIBKRUN_PREFIX` override; then modify the build script
(build.rs) so it does not return early on Linux and emits the matching cargo
directive `cargo:rustc-link-arg=-Wl,-rpath,<dir>` (using the resolved prefix
path), ensuring the same rpath behavior as the macOS branch and keeping the
existing environment override logic.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e620bb83-a64b-427f-b3e5-49b98d4c8382
📒 Files selected for processing (1)
docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md
Comment on lines
+122
to
+128
| - **R1.1**: `build.rs` shall emit `cargo:rustc-link-search=native=` and | ||
| `cargo:rustc-link-arg=-Wl,-rpath,` link directives on Linux in addition to | ||
| macOS. The Linux default prefix shall be `/usr`, with the same | ||
| `LIBKRUN_PREFIX` env-var override as macOS. A comment shall note that on | ||
| Linux the typical install locations are `/usr/lib` (Fedora/RHEL: `dnf | ||
| install libkrun-devel`) and `/usr/local/lib` (source build); CI shall | ||
| install the library at the path used by the runner's provisioning step. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
Fix R1.1 Linux rpath requirement to include a directory and match build.rs
- In
docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md(R1.1),cargo:rustc-link-arg=-Wl,-rpath,is syntactically incomplete; the linker arg must include the directory (-Wl,-rpath,<dir>). - The current
crates/minvmd/build.rsemits the-rpathlink-arg only for macOS and returns early on Linux, so the “on Linux … shall emit” requirement is inconsistent with implementation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md` around lines
122 - 128, Update the R1.1 doc entry to show the rpath linker arg includes a
directory (use `-Wl,-rpath,<dir>`) and mention the Linux default prefix `/usr`
with the `LIBKRUN_PREFIX` override; then modify the build script (build.rs) so
it does not return early on Linux and emits the matching cargo directive
`cargo:rustc-link-arg=-Wl,-rpath,<dir>` (using the resolved prefix path),
ensuring the same rpath behavior as the macOS branch and keeping the existing
environment override logic.
Comment on lines
+238
to
+244
| - **R3.4**: The CI configuration shall add a Linux KVM e2e job. The job runs | ||
| on a self-hosted Linux runner with `/dev/kvm` access (GCP nested-virt or | ||
| equivalent). It provisions libkrun ≥ 1.19.0, materializes the kernel + | ||
| rootfs + initramfs from Minimal packages, sets `MINVMD_E2E=1`, and runs | ||
| `cargo test -p minvmd -- --include-ignored`. The job is allowed-to-fail | ||
| initially (as the macOS e2e job was) and is promoted to required once the | ||
| runner is stable. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Add the env wiring the Linux KVM job actually needs.
R3.4 says the job sets MINVMD_E2E=1, but the verification matrix still requires the kernel/rootfs/initramfs env vars. As written, the CI job description doesn't wire enough inputs to run the gated suite end-to-end.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md` around lines
238 - 244, The CI spec's Linux KVM job only sets MINVMD_E2E=1 but does not
provide the kernel/rootfs/initramfs inputs the gated tests require; update the
job description to wire the kernel, rootfs and initramfs environment variables
(the same kernel/rootfs/initramfs env names used by the verification matrix)
alongside MINVMD_E2E so the e2e run can materialize kernel + rootfs + initramfs
and execute cargo test -p minvmd -- --include-ignored; ensure the spec text
names the exact env vars (e.g., the kernel/rootfs/initramfs env identifiers
referenced in the matrix) and documents their expected sources/values for the
Linux KVM job.
| |------|------|---------|-----------------| | ||
| | R1.5 | — | `cargo build -p minvmd` (Linux) | Exit 0 | | ||
| | R1.5 | — | `cargo test -p minvmd` (Linux, unit tests) | All pass | | ||
| | R2.3 | `MINVMD_E2E=1` + env vars | `minvmd boot --foreground` (Linux) | Prints `vm-up` ≤ 10 s | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the unit ID on the boot smoke-test row.
This row maps minvmd boot --foreground to R2.3, but R2.3 is the cmd/run.rs item; boot is covered by R2.2. That traceability mismatch will send implementers to the wrong work item.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md` at line 388,
The table row currently assigns the `minvmd boot --foreground` smoke-test to
R2.3 but R2.3 corresponds to the `cmd/run.rs` item; update the unit ID to R2.2
so the boot smoke-test correctly maps to the boot work item (change R2.3 → R2.2
for the row containing `MINVMD_E2E=1` + env vars and `minvmd boot
--foreground`), and confirm any related traceability references referencing
`cmd/run.rs` vs boot are consistent.
Contributor
Author
sdd-validate: spec boundary findingsResolved boundary: Spec — PR adds Gate set applied: Spec gates (4 gates). Gate 1 — Acceptance criteria testable ✅ PassAll functional requirements (R1.1–R1.5, R2.1–R2.5, R3.1–R3.5) are verifiable as pass/fail:
No vague aspirations found. Gate 2 — No implementation leakage
|
| Gate | Result |
|---|---|
| 1. Acceptance criteria testable | ✅ Pass |
| 2. No implementation leakage | |
| 3. Assumptions explicit | ✅ Pass |
| 4. Proof artifacts present and behavioral | ✅ Pass |
No Blockers. The spec boundary passes clean. The implementation-leakage Warning is advisory: if the planner later needs flexibility in naming the Linux dispatch function or the Rust module, the spec's named constraints would need a /revise to relax them first.
Generated by sdd-validate for issue #399 · sonnet46 1.2M · ◷
norrietaylor
enabled auto-merge (squash)
June 12, 2026 20:49
norrietaylor
approved these changes
Jun 12, 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
1 participant
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.
Spec for #397: extending
minvmdfrom macOS-only to Linux hosts via libkrun's KVM backend.Demoable Units
Unit 1 — Un-gate libkrun from macOS:
build.rsemits Linux link directives; thekrunmodule,image::kernel_format(), andVmConfig::apply()are un-gated from macOS. No new FFI code — the libkrun API is identical on both platforms.Unit 2 — VMM child on Linux:
cmd/vmm_child.rsandcmd/boot.rsadd Linux paths (identical to macOS paths; no code-signing required). A/dev/kvmcapability check is added.minvmd boot --foregroundon Linux boots a microVM via KVM and receives theREADYmarker from the guest.Unit 3 — Linux e2e + latency benchmark: The existing macOS-only e2e tests (
boot_e2e,minimald_session_e2e,bridge_e2e) are un-gated. A Linux KVM CI job is added. Warm-boot latency on Linux/KVM is measured and reported against the ~75 ms macOS baseline.Open questions resolved
minimal2'sensure_minvmd_running()stays a no-op on Linux; users opt in to VM isolation by runningminvmd run --detachmanually. Full auto-spawn / per-session flag / policy is a follow-up under [Minimal One] Linux host support for minvmd — run sessions in a microVM on Linux #396.minimaldendpoint over UDS) is satisfied by this implementation.Next step
Merging this spec PR advances tracking issue #397 from the spec phase into triage. Please review and merge the spec PR to advance the tracking issue from the spec phase into triage.
Merging the spec PR will close the spec sub-issue (
Closes #398is added to the PR body bysdd-pr-sanitize).References: #397
Closes #398
Summary by CodeRabbit