Firecracker microvm

Run reticulum-go inside an Amazon Firecracker microVM. The default path is aimed at nested VMs (Firecracker inside another VM) where guest TAP networking is unreliable.

Requirements

Linux with /dev/kvm readable
firecracker on PATH
Go toolchain (to build the guest rootfs and host bridge binary)
Optional: pasta only when using NET=1 rootless TAP (often broken when nested)

Quick start

make microvm-up
# or: task microvm:up
# or: ./microvm/up.sh

That will:

Download a Firecracker CI guest kernel into microvm/out/ (first run)
Build a static guest rootfs with busybox + reticulum-go
Start the microVM detached (NET=0, VSOCK only)
Start a host bridge that pipes HDLC into the guest over Firecracker vsock

Stop everything:

make microvm-stop
# or: ./microvm/stop.sh

Add a community hub

Edit microvm/host-bridge.config and uncomment or add an interface under [interfaces], for example:

[[My Hub]]
  type = BackboneInterface
  enabled = Yes
  remote = hub.example.com
  target_port = 4242
  max_reconnect_tries = -1

TCP hubs use TCPClientInterface with target_host / target_port. Then restart:

make microvm-stop
make microvm-up

The host process owns clearnet. The guest joins the mesh through the Microvm Guest pipe (Firecracker vsock CONNECT).

Layout

Path	Role
`microvm/up.sh`	One-shot prepare + start
`microvm/fetch-kernel.sh`	Download `out/vmlinux`
`microvm/build-rootfs.sh`	Build `out/rootfs.ext4`
`microvm/run.sh`	Start Firecracker
`microvm/run-host-bridge.sh`	Host reticulum + vsock pipe
`microvm/stop.sh`	Stop guest, pasta, and host bridge
`microvm/guest/reticulum.config`	Guest config (VSOCK hub, persistent storage)
`microvm/host-bridge.config`	Host config (vsock pipe + your hubs)
`microvm/out/`	Kernel, rootfs, sockets, logs (gitignored)

Networking modes

Default: host bridge (recommended in nested VMs)

NET=0 ./microvm/up.sh

Guest listens on AF_VSOCK. Host uses PipeInterface + vsock-connect.sh to speak Firecracker UDS CONNECT. No guest TAP.

Guest-only

./microvm/up.sh --guest-only
# later:
./microvm/run-host-bridge.sh

Rootless TAP (`NET=1`)

Uses pasta to create a TAP and NAT. Useful on bare metal. Nested Firecracker often fails with tap write errors. Prefer the host bridge there.

NET=1 ./microvm/up.sh --guest-only

Host TAP

If you already have a TAP (requires CAP_NET_ADMIN on the host):

TAP_DEV=tap0 DETACH=1 ./microvm/run.sh

Configure guest IP via microvm/guest/microvm-net before build-rootfs.sh.

Persistence

Guest storage lives on the rootfs under /etc/reticulum/storage (next to the guest config). Rebuilds of rootfs.ext4 replace that disk image. Keep identities you care about outside the image or avoid --rebuild when you need them.

Makefile and Task

Make	Task	Action
`make microvm-up`	`task microvm:up`	Fetch kernel if needed, build rootfs if needed, start guest + host bridge
`make microvm-stop`	`task microvm:stop`	Stop guest and host bridge
`make microvm-kernel`	`task microvm:kernel`	Fetch kernel only
`make microvm-rootfs`	`task microvm:rootfs`	Build rootfs only
`make microvm-rebuild`	`task microvm:rebuild`	Force kernel+rootfs rebuild then up

Logs

Guest serial: microvm/out/firecracker.stdout
Firecracker log: microvm/out/firecracker.log
Host bridge: microvm/out/host-bridge.log