# QEMU microvm machine type

A QEMU machine type (`-M microvm`) explicitly modelled on Firecracker. It strips PCI, ACPI, and most legacy buses out of the i386 platform and replaces device discovery with a fixed virtio-mmio bus, so QEMU itself can serve as a microVM substrate alongside the Rust-rewritten alternatives in [[rust-vmm]]. Positioned in the upstream docs as "a baseline for benchmarking and optimizing both QEMU and guest operating systems" — useful as the C-vintage reference point against which Firecracker and Cloud Hypervisor are measured.

## What's in, what's out

The machine includes ISA bus, LAPIC, IOAPIC (kernel-irqchip=split by default), kvmclock under KVM, fw_cfg, and up to eight virtio-mmio slots. Optional legacy devices: i8259 PIC, i8254 PIT, MC146818 RTC, and a single ISA serial port — each toggleable via machine properties.

Explicitly unsupported:

- PCI-only devices (anything that needs PCI discovery)
- Hotplug
- Live migration across QEMU versions (snapshot/migrate is intra-version only)

The "no PCI, no ACPI" choice is the one that matters. PCI gets you device enumeration and hotplug at the cost of a fairly large emulation surface; ACPI gets you tables, power management, and the standard shutdown path. Dropping both forces virtio-mmio for I/O and triple-fault for shutdown, which is exactly the trade [[microvm]] platforms make.

## Boot flow

QEMU microvm uses `qboot` (a SeaBIOS-compatible minimal firmware) by default, but the firmware cannot boot from virtio-mmio block devices. So the host supplies the kernel directly via `-kernel vmlinux` (and optionally `-initrd`), the same direct-kernel-boot path Firecracker uses. There is no BIOS-level disk boot; the rootfs comes in over virtio-mmio after the kernel is already running.

## Machine properties

Configurable via `-M microvm,<prop>=<value>`:

- `x-option-roms=bool` — disable option ROM loading
- `pit=OnOffAuto` — i8254 PIT
- `pic=OnOffAuto` — i8259 PIC
- `rtc=OnOffAuto` — MC146818 RTC
- `isa-serial=bool` — ISA serial port
- `auto-kernel-cmdline=bool` — auto-inject virtio-mmio device descriptors into the kernel cmdline

The `OnOffAuto` properties default to `auto`, which keeps legacy devices on for compatibility. Turning them all off gets the minimal footprint variant, which depends on the host CPU having TSC_DEADLINE for the LAPIC timer to replace the PIT.

## Usage

Basic invocation with legacy devices enabled:

```
qemu-system-x86_64 -M microvm \
  -enable-kvm -cpu host -m 512m -smp 2 \
  -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda"
```

Minimal-footprint variant — assumes KVM with TSC_DEADLINE, disables every optional legacy device:

```
qemu-system-x86_64 \
  -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off
```

## Shutdown

Without ACPI and without an emulated keyboard there is no soft-off path. The convention is to trigger a triple fault to reboot. Add `reboot=t` to the kernel cmdline so Linux prefers the triple-fault path; pair with `-no-reboot` on the QEMU side so QEMU terminates instead of restarting the guest. This is the same pattern Firecracker uses, modulo the host-side wiring.

## Where this sits next to Firecracker

QEMU microvm and Firecracker overlap on the architectural choices — virtio-mmio, direct kernel boot, no PCI/ACPI — but differ on the surrounding code. QEMU is the C-vintage VMM (~1.7M LOC) with microvm carved out of it; [[rust-vmm]] is the modern Rust ecosystem rewritten from scratch around the same architectural decisions. Firecracker is ~83K LOC of Rust, Cloud Hypervisor ~106K — both an order of magnitude smaller than QEMU's whole codebase, even though the microvm machine type only exercises a slice of it.

The practical implication for [[sandboxing-ai-agents]] use cases: QEMU microvm is useful when you want minimal-microVM semantics on top of an existing QEMU deployment, when [[matryoshka-isolation]] needs a Kata-Containers backend, or when you need a feature Firecracker has refused to add. For green-field agent sandboxes the Rust VMMs are the live choices — see [[microvm-2026]] for the platform survey.

## See also

- [[microvm]] — the architectural concept this implements
- [[microvm-2026]] — Beganović's 2026 industry readout
- [[rust-vmm]] — the modern Rust-rewritten alternative ecosystem
- [[matryoshka-isolation]] — Kata Containers and similar patterns where QEMU microvm is one of the supported backends
- [[sandboxing-ai-agents]] — the broader sandboxing taxonomy
- [[toolbox/pve-microvm]] — packages this machine type as a managed Proxmox VE guest; notably falls back from virtio-mmio to PCIe non-transitional devices because QEMU 10.x MMIO fails to bind net/serial/balloon for Linux guests
- [[spindle-microvm]] — uses this machine type as a per-workflow CI engine in Tangled, with a vsock guest agent and NixOS-from-YAML config
- [[qemu-microvm-docs]] — upstream QEMU documentation source