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, and this page will not invent one: what follows separates what has actually been run from what should work, because a hardware statement nobody has tested is worse than none.

The short list#

Architecture: amd64 only#

packaging/iso/build-iso.sh passes --architecture 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 exists for running the agent off-router against an arm64 VyOS box, which is the developer install and is not the product. Downloading the arm64 .deb will not give you a router. Do not buy an arm64 appliance expecting to install this on it.

Sizing#

Reasoned from what the software does, not measured on a bench. Treat them as a starting point.

Where those 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 — a target, not yet measured in CI or on hardware. 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 Wheelhouse's driver answers no to every RAID question. If you want a mirror, install from the console with install image by hand instead of using the Wheelhouse installer.

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):

Everything else is whatever the stock VyOS kernel has in tree. In practice that is the usual Linux server-NIC coverage — Intel igb/igc/e1000e, Realtek r8169, Broadcom, Mellanox — but that is inference, not a test result. Nobody has verified any specific NIC.

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 interfaces

If 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 actually been run#

The honest inventory, from this repository's own history.

CI runs all four tools/tests suites on every push, along with the agent's Go tests under -race. It does not boot an image or install anything: the installer tests assert the commands a set of answers produces and the answers the driver gives VyOS' installer, not an install.

The ui/ side is not comparable. The agent has over two hundred Go test functions and CI runs them race-clean; ui/ has no tests, and CI only typechecks and builds it. Testing here is not uniform, and it would be misleading to present it as though it were.

If you are evaluating this, install it in a VM first. That is the path with the most evidence behind it, and it exercises the same installer, the same systemd units and the same first-boot sequence as the metal.

Appliance shapes#

Two things worth knowing 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.

Reporting what you find#

If you install on 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. That is exactly the information this page is missing, and it is what turns "should work" into a list. Where to send it: <TODO: owner>.

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.

Checked against docs/hardware.md, docs/install.md, packaging/iso/build-iso.sh, packaging/install-driver.py, packaging/wheelhouse-install, tools/tests, .forgejo/workflows/ci.yml, README.md, PLAN.md.