Questions#

The questions a network engineer asks before putting something on the path between their network and everything else. Several of the answers are unsatisfying; those are the ones worth reading.

Is this just VyOS with a skin on it?#

It is VyOS with an agent and a web interface on top, and this site says so on every page rather than burying it. The kernel, nftables, FRR, Kea, pdns-recursor, strongSwan, OpenVPN, Suricata and Podman are all upstream and unmodified. What Wheelhouse adds is the control-plane agent, the interface, the installer, the app catalogue and the packaging.

"A skin" would be a fair description of a product that hid the model underneath. This one shows it: every editor renders the set lines it will run, and the whole configuration tree is browsable as commands. Where the base ends and Wheelhouse begins.

Why VyOS, and not FreeBSD like everything else in this category?#

Two reasons, and one bill that comes with them.

The configuration model. VyOS has a transactional configuration tree: set builds a candidate, compare shows the diff, commit applies it as one transaction, commit-confirm puts it back if nobody confirms, and every commit is archived as a numbered revision you can diff and return to. That is the product's whole thesis, and it is not something a web interface can add to a system that does not have it. It had to be underneath.

The kernel. nftables, tc and CAKE, in-kernel WireGuard, network namespaces, Podman containers as configuration objects, FRR for BGP and OSPF, and a Debian base where the agent is an ordinary .deb and the drivers are Linux drivers. A FreeBSD appliance is structurally locked out of that list, which is a fact about kernels rather than a criticism of anyone's engineering.

The bill. PLAN.md §3 lists what the choice costs, and none of it is hidden on this site:

• No UPnP or NAT-PMP anywhere in the base, and no credible published miniupnpd image to fall back on. The gap is open.
• No wildcard DNS in the configuration tree, no per-host DHCP option overrides in Kea, and a PXE boot file that cannot be conditioned on client architecture. dnsmasq is in the catalogue as the workaround.
• CAKE is egress-only in the tree: no ingress attachment, no ack-filter, no DOCSIS overhead compensation.
• Committing nat static — one-to-one NAT — through this build's HTTP API stops the API process, while the CLI accepts the same lines. The editor is switched off with the reason on the page, and the table still reads rules made from the console. Verified 2026-09-02.
• The base is a rolling release, so node names move under you. mac-address becoming mac has already cost a day. Images are built from a pinned source tree for that reason.

If those trades look wrong for your network, that is a real conclusion and this page would rather you reached it here than three weeks in.

Can I still use the CLI?#

Yes, and nothing objects. configure, set, compare, commit, commit-confirm, rollback and show configuration commands all work exactly as they did. The agent drives the router through VyOS' own documented HTTP API as a separate program; it stores its state under /config/wheelhouse and touches nothing else in the tree.

A change you make from the console is read back by the interface like any other, because the interface has no private copy of the configuration — it reads the router. Where live state and configured intent disagree, the pages that can tell say so rather than smoothing it over.

There are several things the interface cannot do where the console is the answer, and each page says which. Compared with the VyOS CLI.

Will it run on my hardware?#

There is no compatibility list, and this site will not invent one.

• amd64 only. The build produces one image and it is amd64; UEFI and legacy BIOS both boot. The arm64 .deb exists for running the agent off-router against an arm64 router, and will not give you an image.
• Secure Boot is untested. No signing key exists in the build, so assume you have to turn it off.
• Two network ports, two cores, 2 GB of RAM and 16 GB of disk is the floor; four cores, 4 GB and 32 GB is comfortable, more if you run containers. Those numbers are reasoned from what the software does — two images on disk after an upgrade, 64 MiB allocated per password check for Argon2id — and not measured on a bench.
• No CPU, memory or throughput figure has been measured on any hardware, in CI or out of it. The agent's budget of under 150 MB resident is a target.

Boot the live image on the box and look at ip -br link before you install anything. If the ports are there, the drivers are there. Hardware.

Can I try it without touching my router?#

Three ways, in order of how much evidence stands behind them.

1. Install it in a virtual machine. This is the path with the record: installs to disk in a VM followed by a reboot into the installed system are verified for 0.4.5 by hand and for 0.5.0 from a seed carrying a real router's 214-command configuration. It exercises the same installer, the same units and the same first boot as metal.
2. Run the agent off-router, pointed at a VyOS router you already have. Everything that reads works; the few things that need the router's own filesystem say so instead of pretending. Suricata's alert log is the clearest example — off-router, the IDS page tells you it cannot read it.
3. wheelhouse-agent --demo starts with no router at all, which is enough to click through the interface and drive the API.

What you actually get.

How do upgrades work?#

Three different operations, and only the first is the customer path.

The whole system is VyOS' add system image: a second complete image installed alongside the running one. Both stay on disk. Give the interface the URL of a release ISO, wait for the download and install, and reboot when you choose — the running image does not change until you do. If the new one misbehaves, set the old image as the default boot and reboot, or pick it from the GRUB menu, which is the path that works when the new image will not bring the network up at all.

/config is carried across, so your configuration, your accounts and password hashes, your TOTP secrets, your API tokens, the audit log, the agent's TLS certificate, the VyOS API key and the numbered revision archive all survive.

The agent and interface alone can be replaced with a new .deb on a running router without a reboot. The off-router agent has its own installer script. Neither is the supported customer path today.

Upgrading an image.

What is the release cadence?#

There is no schedule, and this site is not going to invent one.

One version number covers the whole product — agent, interface, installer, packaging and image are built and released from one tag. Versioning is semantic and the changelog follows Keep a Changelog, with security fixes called out in their own section. The first release in that changelog is 0.3.0, dated 2026-09-01, and the current version is 0.5.1. Read that as what it is: a project shipping quickly because it is new, not a cadence anyone has committed to.

There is no long-term-support branch, no published support window for an old version, and no advisory feed separate from the changelog.

Nothing on the router checks for a new release. No update notification, no banner, no call home to ask whether it is current. The download host publishes a machine-readable channel index — stable.json, and beta.json for pre-release tags — naming the newest version, its notes, its checksum file and whether the checksums are signed. Polling it is a cron job you write. Watching for releases.

What happens when the licence server is down?#

Nothing, for a long time, and then reads keep working.

A licence key is a signed statement — plan, features, router limit, expiry, grace period — that the agent verifies offline against a public key compiled into its binary. A router that has never reached the licence server and never will still knows what it holds. The refresh runs about 20 seconds after the agent starts, then once every 24 hours, and retries hourly after a failure. A failed refresh changes nothing: the error is recorded so the Licence page can show it, and the current token stays good until its expiry plus the grace period the key itself carries — seven days on the plans issued today, read out of the signed key rather than hardcoded.

So an outage at the licence server is invisible unless it lasts longer than your token's remaining life. If it does, the write plane closes and everything readable stays readable.

Two consequences worth stating in the same breath. A revoked licence keeps working while the server is unreachable, because revocation only arrives on a refresh. And a router whose clock reads earlier than the licence was issued reports clock-unverified and stays writable — closing the write plane there would lock set service ntp behind the very fault you need to fix.

You can also switch the refresh off entirely with --license-server '', in which case no request is ever made and the key runs to its own expiry. Privacy, the licence gate.

What happens if I stop paying?#

The router keeps routing, and you keep seeing it.

An unlicensed or lapsed agent signs you in and shows every page, every counter, every log line, the configuration tree and the whole audit trail. What it refuses is the write plane: staging, commit, commit-confirm, discard, direct configure, rollback, save, load, reconcile, capture and the app-store actions. Each refusal is an HTTP 402 with a sentence naming the fix rather than a blank failure.

The list is not marketing shorthand. It is one middleware function wrapped around a specific set of routes, and you can read it:

grep -n 'licensed(' agent/main.go

The administration plane is outside that gate too, which is deliberate: you can still manage accounts and API tokens, install a system image, reboot the box and paste in a new licence key with no licence at all.

Losing sight of your network because a card expired would be a worse product than losing the ability to change it. Pricing.

What if I lock myself out?#

Three different accidents with three different answers, and one of them is unsatisfying.

You committed the change that cut you off. This is what commit-confirm is for. The Commit Bar recognises the paths that strand operators — the firewall, NAT, an interface's own addressing, the default route, the failover and load-balancing protocols, policy routes, system login, the PKI, SSH and the API, and anything at all on an interface the router is currently leaving through — and offers a confirmation window instead of a bare commit. Miss the confirmation and the router reboots into the previous configuration. It is the configuration backend's own mechanism, so nothing in your browser or in the agent is holding it. How commit-confirm works.

You lost the password or the phone. There is no admin reset for another account's second factor and there are no recovery codes. If you created a break-glass token (--admin-token-file; nothing creates one for you, so most installs have none) it still authenticates as admin against the API. Otherwise the documented recovery is a console shell: stop the agent, edit /config/wheelhouse/state.json by hand, start it again.

You cannot reach the box at all. The console. An install creates a wheelhouse account, and the base system's own vyos account is kept beside it with the same password, because the base's login and sudo handling depend on it existing. It is your recovery account, and whatever you do to one you should do to the other.

Lockout recovery.

Does it phone home?#

One request every 24 hours, to one host, carrying four fields: the licence key, a fingerprint of the installation, the router's host name and the agent version. The fingerprint is 16 hexadecimal characters derived from /etc/machine-id by a one-way hash; it exists so the plan's router limit can count.

There is no telemetry, no analytics, no crash reporting, no usage metrics and no update check. Nothing counts your rules, your interfaces, your clients or your traffic and sends the number anywhere. The connection reveals what any HTTPS request reveals: your public address and the time.

It is one flag to turn off, with the consequence stated — a renewal will not reach the router on its own, and a revoked key will not stop working. Privacy.

Is my configuration portable, or am I trapped?#

It is a VyOS configuration, which is the answer to both halves.

show configuration commands on the console prints the whole running configuration as set lines. So does GET /api/config/commands through the API. Download config on the System page saves the running configuration as <hostname>-config.boot. Every commit is archived as a numbered revision under /config/archive, which is VyOS' own mechanism and not something the agent invented.

Remove the agent and you have a VyOS router with your configuration on it. There is no proprietary configuration format, which is a consequence of building on someone else's configuration model rather than a promise this site is making.

Coming the other way, tools/opnsense-import.py reads an OPNsense config.xml and writes VyOS commands plus a report of what came across, what came across differently and what could not; --check-against then compares a running router with the configuration it should have. It is not one click — it writes commands and a report a person reads. Migrating from OPNsense.

What if you disappear?#

An honest answer in three parts, and the third one is bad.

The router does not stop. The agent is a self-hosted binary with no dependency on any server except to renew a licence, and a key verifies offline. If the licence server vanished tomorrow, a licensed router would keep accepting changes until its token expired plus its grace period, would keep showing you everything after that, and the console would keep working regardless.

The base is GPL and its source ships with every release. SOURCES-<version>.txt names the exact vyos-build commit and every installed package, and the patch to that build tooling is published beside it. Both files are also on the installed system under /usr/share/doc/wheelhouse/, so a customer holding only the box can find them. You could rebuild the operating system underneath.

The agent and the interface are proprietary, and there is no source escrow and no published continuity commitment. <TODO: owner>. That is a real risk and this page is not going to describe it as anything else.

Is it open source?#

No. The agent and the interface are proprietary programs that drive GPL components as separate processes, over a documented API. The base is GPL and its corresponding source is published with every release. Neither half of that sentence should be softened in either direction. Dependency licences and the boundary.

What does it cost?#

Not decided. A subscription unlocks configuration changes, reading is free forever, and both monthly figures are unset. Nothing is for sale yet, and neither the licence agreement nor the terms of service has been written. Pricing.

Can my team use it without sharing one password?#

Yes. Local accounts with Argon2id and TOTP, three roles enforced server-side on every route, API tokens that carry a role and an expiry and are stored only as a hash, and OIDC single sign-on with group-to-role mapping. Every change records who made it, with what role, from which address, and the commands it ran.

The limits, in the same breath: no per-object permissions, no hardware-key second factor, no recovery codes, no administrator reset of a second factor, and an audit log that cannot leave the box and is not tamper-evident. Accounts and access control.

Where do I report a bug or a vulnerability?#

A vulnerability goes through the disclosure process; a bug goes to support. Both need an address, and neither address is published yet. The forge is private, so there is no public issue tracker, no forum and no chat channel. That is a real gap, not an oversight in this page. Support.

What is the catch?#

That it is young, and that youth shows in specific places rather than in general.

No complete install to disk on physical hardware is on record. There is no hardware compatibility list, no VM image and no arm64 image. Releases are not signed. There is no alerting, no packet capture, no UPnP and no device inventory. IPv6 is configurable and not observable. The audit log cannot leave the box. The interface has no tests, while the agent has over two hundred. There is no price, no terms and no support address.

All of it is on one page, which is the closest thing to an answer this site can give: what is finished, and what is not.