Getting started#
This section takes you from nothing to a working router. Download the image, check it, write it to a stick, boot it, answer the installer's questions, sign in, and spend the first hour doing the four things that matter. Allow about twenty minutes for the install itself, most of it waiting for a squashfs to copy. Everything here describes the keyboard-and-screen path first, because the unattended path automates exactly these answers and is easier to trust once you have seen them asked.
Read it in this order#
| Page | What it assumes | |
|---|---|---|
| 1 | What Wheelhouse is | Nothing. Read it if you have not decided yet. |
| 2 | What you need | You are choosing or borrowing a machine. |
| 3 | Download and verify | You have a network and about 600 MB of patience. |
| 4 | Write the stick | You have the ISO and a USB stick you can erase. |
| 5 | Boot it | The stick is written and the machine will boot from it. |
| 6 | Every installer question | You are looking at the welcome screen. |
| 7 | What the installer does | You pressed Install and want to know what the clock is counting. |
| 8 | First sign-in | The machine has rebooted into the installed system. |
| 9 | Enter a licence | You are signed in and want to change something. |
| 10 | The first hour | The router works. Now make it yours. |
The other ways in#
Four paths branch off the middle of that list. Each is a full page rather than a footnote, because each one is where a particular kind of install goes wrong.
- Installing in a VM — the path with the most evidence behind it, and the sensible way to evaluate the product.
- Boxes with one port — a single-NIC machine installs, but the installer asks you a question it does not ask anyone else.
- Serial consoles — on a headless box the installer does not take the console; you run it.
- Installing without a keyboard — hand the machine a seed and it installs itself. This is how you build more than one.
And two that start somewhere other than a blank disk:
- Coming from OPNsense — export, import, read the report, build a seed, install, verify against the router you replaced.
- The developer install — running the agent off-router against an existing VyOS box. It is not the product and it is not supported; it is here so that material naming port 8090 does not confuse anyone.
When something stops, If the install goes wrong is the page with the log paths and the handful of failures that actually happen.
What this section will not tell you#
There is no hardware compatibility list. There is no list because nobody has tested enough machines to write one, and a compatibility statement nobody has tested is worse than none. What you need says exactly what has been run and what has not, including the fact that a complete install to a disk on physical hardware, followed by a reboot into the installed system, is not on record. Every end-to-end verification in the repository names a virtual machine.
Nothing here promises an upgrade path it has not exercised. An add system image
upgrade of a Wheelhouse box has not been recorded on hardware or in a VM.
Where this fits#
Wheelhouse is built on VyOS, which is GPL-licensed, on a Debian base. The kernel, nftables, FRR, Kea and the container runtime are VyOS'; Wheelhouse adds the agent, the web UI and the installer described in this section. About Wheelhouse covers the attribution, the licence boundary and how to get the corresponding source.
Where to go after this section#
- How Wheelhouse works — the five ideas the rest of the documentation assumes: the configuration tree, staging, the Commit Bar, commit-confirm, revisions.
- The manual — a page per screen.
- Task guides — backup, restore, upgrade, SSH, lockout recovery.
- Reference — flags, endpoints, status codes, metrics.
See also#
- What Wheelhouse is — the product in one page.
- What is not finished — the honest status page, in the product's own words.
- About Wheelhouse — what it is built on and where the licence boundary sits.
- The product site — the case for it, and what it costs.
- Downloads — images, checksums and the corresponding-source record.
Checked against docs/install.md,
docs/hardware.md,
docs/unattended-install.md,
docs/README.md, README.md.