microheart

Boot a Firecracker microVM with one command or three lines of Python. No Python dependencies. Linux with KVM only.

Unofficial. Not affiliated with or endorsed by Amazon Web Services. "Firecracker" is an AWS project and name.

Status: alpha. The code has not been tested on a real host yet. Test it before you rely on it. See SECURITY.md for the known limits.

What it does

Firecracker is a very small virtual machine monitor (3.6 MB). It starts a Linux guest in about a second, but you must do many manual steps first: get the binary, get a kernel, build a disk, make a network device, set NAT, write the API calls. microheart does these steps for you.

Requirements

To run a VM

• Linux, x86_64 (or aarch64), with /dev/kvm readable and writable by root
• Root access (sudo): TAP devices and iptables need it
• ip, iptables, sysctl, ssh (normally present)
• Python 3.9 or newer
• A virtualization-capable host. A cloud VM works if nested virtualization is on (tested idea: DigitalOcean droplet)

To build the root disk (once, on any machine)

• Docker, mkfs.ext4, e2fsck, ssh-keygen

Docker is not needed to run the VM. Build the disk once and copy the .ext4 file.

Install

pip install microheart

Quick start

sudo microheart fetch            # Firecracker + kernel (skipped when bundled in the wheel)
sudo microheart build-rootfs     # build alpine.ext4 + an SSH key (needs Docker)
sudo microheart up               # boot the VM and wait for SSH
sudo microheart ssh uname -a     # run one command, or open a shell without arguments
sudo microheart down             # stop the VM, remove tap0 and the NAT rule

Files go to ~/.cache/microheart/ (change with MICROHEART_HOME). With sudo, ~ is root's home.

Command reference

Global options (before the command): --rootfs FILE, --key FILE, --vcpu N (default 1), --mem MIB (default 256).

Python API

from microheart import MicroVM

with MicroVM("alpine.ext4", "vm_key", vcpu=2, mem_mib=512) as vm:
    print(vm.ssh("uname -a").stdout)

How it works

1. assets.py finds the Firecracker binary and kernel (bundled, then cache, then download).
2. net.py makes tap0 with host IP 172.16.0.1/30, turns on IP forwarding and adds MASQUERADE.
3. vm.py writes vm_config.json and starts firecracker --config-file ... --enable-pci.
4. The guest MAC 06:00:AC:10:00:02 and the disk's /etc/network/interfaces give the guest 172.16.0.2/30 with gateway 172.16.0.1. DNS (8.8.8.8) is written at boot.
5. microheart polls SSH until the guest answers.

Network layout:

guest eth0 172.16.0.2/30 <--virtio--> host tap0 172.16.0.1/30 --NAT--> host default interface --> internet

One VM at a time for now: the IP addresses and tap0 are fixed.

Root disk recipe

src/microheart/data/ holds the recipe:

• Dockerfile: Alpine 3.20, OpenRC, OpenSSH, iproute2, curl. SSH is key-only.
• files/: network config, DNS at boot, serial console options.
• build-rootfs.sh: Docker image to folder, add your public key, mkfs.ext4 -d, e2fsck.

Edit the recipe to add your own packages, then run build-rootfs again.

Security notes

• The serial console logs in as root with no password (test setting). Edit data/files/etc/conf.d/agetty.ttyS0 before real use.
• SSH accepts keys only. The key is made on your machine and is never part of the package.
• The guest can reach the internet through host NAT. The guest and host FORWARD policy is set to ACCEPT.
• Firecracker's jailer (extra isolation) is not used yet.
• microheart runs as root and changes host network settings. Read the code first.

Limits and roadmap

• Alpha, untested on a real host.
• One VM at a time (fixed addresses).
• No snapshots, no jailer, no multi-VM networking.
• Planned: per-VM addresses, --config-file options, snapshots, jailer support, aarch64 tests.

Development

See CONTRIBUTING.md. Build a wheel with the binary and kernel inside:

python scripts/bundle.py && python -m build --wheel
wheel tags --platform-tag manylinux_2_17_x86_64 --remove dist/*.whl

License

MIT, see LICENSE. Third-party software (Firecracker: Apache-2.0; Linux kernel: GPL-2.0) is downloaded or bundled unchanged. See NOTICE.