Installing in a VM#

A virtual machine is the tested path and the sensible way to evaluate Wheelhouse. Attach the ISO as a virtual CD, give the machine a disk and at least two NICs, and follow the same installer as a physical box: it is the same image, the same systemd units and the same first-boot sequence. Every end-to-end verification recorded in this repository names a VM, which is exactly why it is the path to start on.

What to give it#


Firmware	UEFI or legacy BIOS; both are built into the image. Turn Secure Boot off.
CPU	two cores minimum, four is comfortable
Memory	2 GB minimum, 4 GB comfortable, 8 GB if you plan to install container apps
Disk	one virtual disk, 16 GB minimum, 32 GB or more comfortable
NICs	at least two — one WAN, one LAN. `virtio` works; that is what the bench VMs use.
Optical	the ISO, attached as a virtual CD

virtio disks work too. Nothing about the install differs from the physical path from the boot menu onwards, so Boot it and Every installer question are the pages to follow.

There is no appliance image#

Cloning a VM you built#

If you want one machine template, build it once and clone it. Two things must be different on every copy.

Regenerate /etc/machine-id. The licence fingerprint and the DHCP client identity are both derived from the machine's identity, so a fleet of clones sharing one machine-id is a fleet of routers that count as the same installation to the licence server and hand the same client identity to your provider.

Give each clone its own host name. It is the router's name, the common name on the self-signed certificate, and how you will tell them apart in the fleet view.

If what you actually want is many identical machines built from one description rather than one machine cloned, use a seed instead — Installing without a keyboard is the right tool for that, and it makes each machine's identity fresh by construction.

Using a seed on a VM#

A seed is easier on a VM than on hardware: build the ISO and attach it as a second virtual disk rather than writing a USB stick.

bash

tools/wheelhouse-seed.py --user-data seed.yaml --out seed.iso

Then attach seed.iso alongside the Wheelhouse ISO and boot. The installer finds it, installs to the machine's only other disk, and reboots.

That behaviour — refusing to reinstall over itself with the seed medium still attached — is one of the things that has been verified on a VM.

What has been verified this way#


Booting the live image in a VM	Yes, repeatedly.
Installing to a disk and rebooting into it	Yes, for 0.4.5 keyboard-driven and again for 0.5.0 unattended from a seed carrying a real router's 214-command configuration.
Refusing to reinstall over itself with the seed still plugged in	Yes.
Multi-WAN behaviour	Verified on a dual-WAN VM built from the ISO.

None of that is a substitute for the missing row: a complete install to a disk on physical hardware, followed by a reboot into the installed system, is not recorded. What you need has the whole inventory.