What you need#
A 64-bit x86 machine with two Ethernet ports, a disk that is not the medium you booted from, a USB stick you can erase, and a screen and keyboard or a serial console. There is no hardware compatibility list. This page separates what has been run from what should work.
The short list#
| Machine | x86-64 (amd64). This is the only image the build produces. |
| Ethernet ports | Two. One box installs with one — see Boxes with one port. |
| Disk | Anything that is not the medium you booted from; the installer hides that one. 16 GB or more. |
| USB stick | 2 GB is plenty. It is erased. |
| Console | A screen and keyboard, or a serial console — see Serial consoles. |
| Download | About 600 MB. |
Architecture: amd64 only#
The image build targets amd64 and the download host carries one image per release. There is no arm64 image.
An arm64 agent package is built and published on every tag. It is for running the
agent off-router against an arm64 VyOS box, which is the
developer install and is not the product. The arm64 .deb will
not give you a router. Do not buy an arm64 appliance expecting to install this on it.
Sizing#
These are design targets rather than measurements. Treat them as a starting point.
| Minimum | Comfortable | |
|---|---|---|
| CPU | any 64-bit x86 with two cores | four cores; an Intel N100-class SoC is the shape this is designed around |
| RAM | 2 GB | 4 GB, or 8 GB if you run containers from the app store |
| Disk | 16 GB | 32 GB or more |
| NICs | 2 | 2 or more |
Where they come from:
- Disk. The image is about 595 MB, and VyOS keeps the previous image alongside the new one after an upgrade, so two are on disk most of the time. Add the configuration archive, the container images if you install apps, and the journal. 16 GB is tight but workable; 8 GB will install and then run out.
- RAM. The agent's budget is under 150 MB resident and under 3% idle CPU on an N100. On top of that, each password check allocates 64 MiB for Argon2id for about 60 ms, so simultaneous logins are the memory spike. Then VyOS itself, plus podman and whatever containers you install.
- CPU. Argon2id at three passes over 64 MiB is the only deliberately expensive thing the agent does. Routing performance is VyOS' and the kernel's.
Storage#
The installer offers every block device lsblk reports as a disk that is not the medium
you booted from, with its size and model. Loop, zram, optical, ramdisk and floppy devices
are filtered out. NVMe, SATA and USB disks all appear.
You can install onto a USB stick. Do not: the configuration archive, the journal and
state.json are written continuously, and flash without wear levelling will die.
RAID-1 is offered by VyOS' own image installer, and the Wheelhouse installer answers no
to every RAID question. For a mirror, install from the console with install image by hand
instead.
Network interfaces#
The image carries the stock VyOS kernel — 6.18.48 in 0.5.1 — plus vyos-linux-firmware
and VyOS' out-of-tree driver packages. From the shipped image's own package manifest
(SOURCES-0.5.1.txt):
| Package | Covers |
|---|---|
vyos-intel-i40e, vyos-intel-iavf | Intel X710/XL710/X722 and their virtual functions |
vyos-intel-ice | Intel E810 |
vyos-intel-ixgbe, vyos-intel-ixgbevf | Intel 82598/82599/X520/X540/X550 and virtual functions |
vyos-intel-qat | Intel QuickAssist crypto acceleration |
vyos-drivers-realtek-r8152 | Realtek USB Ethernet adapters (RTL8152/8153/8156) |
vyos-linux-firmware | non-free firmware blobs the kernel loads at probe time |
amd64-microcode, intel-microcode | CPU microcode, applied at boot |
Everything else is whatever the stock VyOS kernel has in tree — in practice the usual
Linux server-NIC coverage, Intel igb/igc/e1000e, Realtek r8169, Broadcom,
Mellanox. That is inference, not a test result. No specific NIC has been verified.
To find out for a box you are considering, boot the live image on it and look before you install anything:
ip -br link
show interfacesIf your ports appear there with a MAC address, the driver loaded. If they do not, no amount of configuration will help: there is no mechanism in this product to add a driver or a firmware blob to the image.
Wireless is not surfaced. VyOS can configure interfaces wireless from the CLI; the
Wheelhouse UI has no page for it and the installer does not offer it.
Firmware and boot#
The image is a hybrid ISO and carries both grub-efi-amd64 and grub-pc, so UEFI and
legacy BIOS boot are both built in.
What has been verified#
| Status | |
|---|---|
| Booting the live image in a VM | Yes, repeatedly. |
| Booting the live image on physical hardware | Yes. |
| Installing to a disk in a VM and rebooting into it | Yes, both keyboard-driven and unattended from a seed. |
| Installing to a disk on physical hardware, then rebooting into it | Yes, on one machine, several times. |
| Refusing to reinstall over itself when the seed medium is left plugged in | Yes, in a VM. |
| The configuration an install writes, for a given set of answers | Tested. wheelhouse-install --answers FILE --commands prints the set lines without touching anything. |
| VyOS' image installer being driven correctly | Tested against a scripted stand-in for its prompts. |
| Any hardware but that one machine | Not recorded. One machine is not a compatibility list. |
An add system image upgrade of a Wheelhouse box | In a VM only, once, on 2026-09-03. None on hardware. |
| Any CPU, memory or throughput measurement on real hardware | None. |
The automated tests assert the commands a set of answers produces and the answers the driver gives VyOS' installer. They do not boot an image or install anything.
If you are evaluating this, install it in a VM first. It exercises the same installer, the same systemd units and the same first-boot sequence as the metal, and it costs you no hardware if you decide against the product.
Appliance shapes#
Two things to know before you buy a box, neither of which is a compatibility claim.
- A four- or six-port appliance installs with one LAN port configured. The installer asks for one WAN and one LAN; the remaining ports come up unconfigured. There is no bridge, VLAN or LAG option in the installer. Add them from Network → Interfaces afterwards, or from the console.
- The installer's WAN is DHCP or a static address. No PPPoE, and no VLAN tag on the WAN. If your ISP needs either — much DSL and a lot of FTTH does — skip the WAN question and configure it afterwards from the UI, which does model PPPoE.
Recording an install on new hardware#
The useful things to record are the board or appliance model, the NIC controllers
(lspci -nn | grep -i net), whether Secure Boot had to be turned off, and whether every
port showed up.
There is nowhere to send it yet — no public support address, issue tracker or chat channel exists. Keep the notes; they will be the first rows of the compatibility list when there is somewhere to put them.
See also#
- Installing in a VM — the tested path.
- Boxes with one port — a single-NIC install, and the question it raises.
- Serial consoles — headless machines.
- Download and verify — the next step.
- What is not finished — the full list, kept current.
- Interfaces — where the ports the installer left alone get configured.
- Upgrading the image — the procedure, and what has and has not been exercised.