pve-microvm
A Debian package that adds QEMU microvm machine type support to Proxmox VE.
Runs OCI container images, Firecracker rootfs images, unikernels, and alternative OS as lightweight hardware-isolated VMs.
⚠️ Highly experimental. This project patches
qemu-serverinternals and has not been tested in production. Use at your own risk. The patches are fully reversible — uninstalling the package restores the original files.
📝 Blog post with some background · ❓ FAQ
Why
We needed something between LXC containers and full QEMU VMs for running coding agents and other semi-trusted workloads.
| LXC | microvm | Standard VM | |
|---|---|---|---|
| Isolation | Namespace (shared kernel) | KVM (own kernel) | KVM (own kernel) |
| Boot time | ~50 ms | < 300 ms | 2–10 s |
| Overhead | Minimal | Minimal | Moderate |
| Attack surface | Broad (host kernel) | Minimal (virtio-pcie) | Broad (emulated PC) |
| Untrusted code | ⚠️ risky | ✅ safe | ✅ safe |
Hardware-isolated VMs with container-like speed, managed through the same
Proxmox tools you already use. No new runtime — QEMU's microvm machine type
is already on every PVE node.
Highlights
- 50 features shipped — templates, cloning, networking, HA, web UI, backups
- 21 guest OS — 13 Linux distros + SmolBSD, OpenWrt, OPNsense, 9Front, OSv, gokrazy, Firecracker
- 31 ms boot (SmolBSD) to ~2 s (Alpine) to ~8 s (Debian)
- Create µVM button in PVE web UI with OCI image picker
- All storage backends — LVM, LVM-thin, ZFS, NFS, CIFS, Ceph
- HA + migration — offline migration in 2 seconds, ha-manager relocate
- Tested on 4 nodes — from Atom x5-Z8350 (2 GB) to i7-12700 (128 GB)
Quick start
# Install (always fetches the latest release)
curl -sLO $(curl -s https://api.github.com/repos/rcarmo/pve-microvm/releases/latest | grep browser_download_url | grep '.deb' | cut -d'"' -f4)
dpkg -i pve-microvm_*.deb
# Create a template from any OCI image
pve-microvm-template --image debian:trixie-slim
# Clone and boot
qm clone 9000 901 --name my-sandbox --full
qm start 901
qm terminal 901Or use the Create µVM button in the PVE web UI.
Supported guests
| Category | Images |
|---|---|
| Linux (apt) | Debian, Ubuntu |
| Linux (apk) | Alpine |
| Linux (dnf/tdnf) | Fedora, Rocky, Alma, Amazon, Oracle, UBI, Photon, Azure Linux |
| Router/Firewall | OpenWrt, OPNsense |
| BSD | SmolBSD (NetBSD, 31ms boot) |
| Plan 9 | 9Front |
| Unikernel | OSv, gokrazy |
| Compatible | Any Firecracker rootfs (ext4 import) |
What's included
| Component | Description |
|---|---|
pve-microvm-template | Create PVE templates from OCI images or specialist OS |
pve-oci-import | Convert any OCI image to a bootable microvm disk |
pve-microvm-share | Share host directories via virtiofs |
pve-microvm-9p | Share host directories via 9p (no daemon) |
pve-microvm-ssh-agent | Forward SSH agent via vsock |
pve-microvm-run | Ephemeral microvms (run and destroy) |
pve-microvm-bench | Boot time and overhead benchmarking |
| Web UI | Create µVM dialog, ⚡ icon, xterm.js console, panel hiding |
| Kernel | Pre-built 6.12.22 with PCIe virtio + vsock + virtiofs |
Tested on
| z83ii (worst-case) | borg (reference) | |
|---|---|---|
| CPU | Atom x5-Z8350 @ 1.44 GHz | i7-12700 @ 4.9 GHz |
| RAM | 2 GB | 128 GB |
| PVE | 9.1.9 (qemu-server 9.1.8) | 9.1.7 (qemu-server 9.1.6) |
| QEMU | 10.1.2 | 10.1.2 |
Full cluster: 4 nodes — see Cluster Hardware.
Documentation
- Installation — install, verify, uninstall
- Quick Start — templates, cloning, basic usage
- Guest OS — all supported distributions and specialist OS
- Networking & Storage — virtiofs, 9p, vsock, SSH agent
- Web UI — Create µVM dialog, console, icons, panel hiding
- Configuration — supported/unsupported options
- Architecture — how it works, QEMU command line
- Firecracker Compatibility — importing rootfs images
- High Availability — migration, HA relocate
- Test Matrix — distros, features, hardware
- Cluster Hardware — all 4 nodes
- Known Issues — workarounds and fixes
- Limitations — what doesn't work (yet)
- Troubleshooting — common problems
- FAQ — frequently asked questions
- Development — repo structure, building
- Changelog — full feature list and release history
Roadmap
| Feature | Priority |
|---|---|
| Network off by default | Medium |
| Egress allow-list (nftables) | Medium |
| Declarative VM config (TOML) | Low |
| GPU passthrough | Low |
| AArch64 guest support | Low |
| Upstream RFC for pve-devel | Low |