feat: add libkrun backend for macOS (vsock + native Hypervisor.framework)

[aniketmaurya]

Problem

SmolVM uses QEMU on macOS, which has significant limitations:

• Slirp networking: host cannot reach guest IP directly
• No vsock support through SmolVM's QEMU backend
• Port forwarding requires SSH tunnels (guest must run sshd)
• Slow boot (~2-3s) compared to Firecracker on Linux (~500ms)

This forces users to either run SSH in their guest images or use workarounds like expose_local() for host→guest communication.

Proposal

Add libkrun as a third backend alongside Firecracker and QEMU.

libkrun is a lightweight VMM that uses Apple's Hypervisor.framework on macOS (and KVM on Linux). Key advantages:

• Native virtio-vsock — direct host↔guest communication without networking
• TSI (Transparent Socket Impersonation) — network connectivity without a virtual NIC
• Fast boot — comparable to Firecracker (~500ms)
• Lightweight — ~5MB library vs QEMU's ~200MB
• OCI image support — can boot from container images via krunvm

Benefits

• Unified vsock path: same guest agent communication on both Linux (Firecracker) and macOS (libkrun)
• No SSH dependency: guest images don't need sshd for port forwarding
• Faster dev loop: sub-second boot on macOS
• Simpler networking: vsock replaces SSH tunnels + port forwarding

Implementation

1. New runtime_libkrun.py adapter following the pattern of runtime_firecracker.py and runtime_qemu.py
2. Add libkrun option to backend detection (auto selects libkrun on macOS if available, falls back to QEMU)
3. vsock device configuration (already supported in VMConfig via feat: add virtio-vsock support for Firecracker VMs #141)
4. Process management for libkrun-based VMs

References

• libkrun — the VMM library
• krunvm — CLI for libkrun
• libkrun-efi — EFI variant for macOS
• SmolVM feat: add virtio-vsock support for Firecracker VMs #141 — vsock support (merged)

[aniketmaurya]

@codex please evaluate this issue and create a plan with pros and cons.

[chatgpt-codex-connector]

Evaluation of the PR issue

Great request. Based on the trigger, this should be treated as a design/architecture evaluation (not immediate code changes): whether adding a libkrun backend on macOS is a good next step, and how to stage it safely.

What looks strong

• The problem statement is aligned with current code reality: backend auto-resolution currently chooses QEMU on Darwin, so macOS inherits QEMU tradeoffs by default today.
• The proposal fits existing abstractions: VMConfig already has a vsock field, so a third runtime can plug in without inventing a new user-facing concept.
• There is product value overlap with an existing limitation: docs explicitly call out QEMU’s networking model as a blocker for some host-side controls, so a new backend path could unlock better behavior on macOS too.

---

Pros and cons

Pros

• Better host↔guest communication primitive on macOS (vsock-first parity with Firecracker-style workflows).
• Potentially faster startup and smaller footprint versus full QEMU process model (as claimed by libkrun/krunvm docs).
• Cleaner long-term backend story if “auto” can use best-native hypervisor per platform.

Cons / risks

• TSI constraints are real: libkrun documents networking limitations (socket family/type constraints, custom-kernel requirement for some modes), so assumptions about “drop-in networking replacement” need validation in SmolVM use-cases.
• Platform constraints: libkrun macOS docs indicate modern macOS/ARM64-oriented path; this may complicate Intel mac support expectations.
• Operational complexity: adding a third backend affects backend resolution, runtime lifecycle, doctor diagnostics, docs, and test matrix (not just one runtime adapter file).
• Security model differences: libkrun notes guest/VMM context coupling; policy features (like egress controls currently Firecracker-oriented) may need explicit redesign for consistency.

---

Recommended implementation plan (phased)

Phase 0 — Feasibility spike (no user-facing default changes)

1. Add an experimental backend constant (libkrun) and internal adapter skeleton.
2. Validate minimum lifecycle: create/start/stop/delete on macOS ARM64.
3. Validate vsock bootstrapping and one host↔guest RPC path.
4. Publish a short benchmark note (cold boot p50/p95, failure modes).

Pros: low blast radius, fast learning.
Cons: temporary code path duplication.

---

Phase 1 — Opt-in backend (explicit only)

1. Permit backend="libkrun" explicitly; keep auto behavior unchanged initially.
2. Implement capability checks in doctor/diagnostics (installed binary/library, host arch/os, kernel/rootfs compatibility).
3. Mark unsupported features clearly (if any): egress controls, snapshots, special forwarding modes, etc.

Pros: safe rollout, real user validation.
Cons: users must opt in manually.

---

Phase 2 — Auto-resolution upgrade

1. Change Darwin auto resolution to: libkrun if available, otherwise qemu.
2. Add compatibility fallback guardrails and crisp warning messages.
3. Add migration notes in docs (what changes when users rely on auto).

Pros: delivers the main UX win.
Cons: behavior change for existing macOS users; requires careful release notes.

---

Phase 3 — Hardening and parity

1. Expand integration tests by backend (startup, networking behavior, port forwards, vsock flows).
2. Revisit feature parity table for Firecracker/QEMU/libkrun.
3. Decide deprecation strategy for QEMU-on-mac default only after stability data.

Pros: predictable long-term maintenance.
Cons: larger CI/runtime matrix cost.

---

Decision summary

I’d classify this proposal as high-value, medium-to-high implementation risk, and recommend proceeding with the phased rollout above (Phase 0 → Phase 1 first), then promote to auto only after capability/compatibility confidence is established.

---

Commands I used for this evaluation

• ✅ find .. -name AGENTS.md -print
• ✅ rg -n "runtime_(qemu|firecracker)|backend|vsock|VMConfig|libkrun|krun" src tests docs | head -n 200
• ✅ sed -n '1,260p' src/smolvm/backends.py
• ✅ sed -n '1,220p' docs/concepts/network-egress-controls.md
• ✅ nl -ba src/smolvm/types.py | sed -n '70,280p'
• ✅ nl -ba src/smolvm/backends.py | sed -n '1,220p'
• ✅ Web validation on libkrun/krunvm docs and README sources (links below)

---

External references used

• libkrun README (official): https://raw.githubusercontent.com/containers/libkrun/main/README.md
• krunvm README (official): https://raw.githubusercontent.com/containers/krunvm/main/README.md
• krunvm macOS docs: https://mintlify.wiki/containers/krunvm/platforms/macos

View task →