#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-server internals 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.

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 901

Or use the Create µVM button in the PVE web UI.

#Supported guests

#What's included

#Tested on

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

#License

Apache-2.0