Built on VyOS#

Wheelhouse is built on VyOS, which is free software under the GNU General Public License, version 2, on a Debian base. The kernel, nftables, FRR, Kea, pdns-recursor, WireGuard, strongSwan, OpenVPN, Podman and the configuration tree they all read are VyOS' work. Wheelhouse adds four things — the agent, the web UI, the installer and the app catalogue — and each of them is a separate program that drives VyOS over its documented HTTP API and its op-mode commands. Below: where that line is drawn, which base each image is built from, and what upstream cannot express.

What the base provides#

Everything in this column exists because VyOS built it, and the product would not be possible without it.

From VyOS	What Wheelhouse does with it
A transactional configuration tree: `set` → staged diff → `commit` → commit-confirm → versioned revisions → `rollback`	The Commit Bar, the staged diff, the confirm window and the revision list are this mechanism, driven from a browser
Linux kernel networking: nftables, `tc` and CAKE, in-kernel WireGuard, VLANs, bridges, bonds, tunnels	The Firewall, QoS, Interfaces and VPN pages read and write it through the tree
FRR: BGP, OSPF, IS-IS, BFD, VRRP	The routing and high-availability pages
An HTTP API over the whole configuration tree	The agent's only way in. It posts form-encoded requests to the REST endpoints
Op-mode commands (`show …`)	Operational state: counters, conntrack, routes, leases, certificates
Podman containers as configuration objects (`set container …`)	The app catalogue. An app install is a configuration diff, which is why it rolls back
A Debian base	The agent ships as a plain `.deb`, and the drivers are Linux drivers

The REST endpoints stay off until service https api rest is set, which first boot does. A router that has not had it set answers 404 {"detail": "Not Found"} to everything, and the agent says so rather than reporting an empty router.

What Wheelhouse adds#

wheelhouse-agent — a single Go binary, run by systemd as root. Staging, native commit-confirm, revision rollback, an attributed audit log, parsed operational state, a telemetry WebSocket, accounts with Argon2id and TOTP, four roles enforced per route, scoped API tokens, OIDC single sign-on, Prometheus metrics, TLS, and the web UI served from the directory --ui-dir names, /usr/share/wheelhouse/ui on the appliance.
The web UI — a React single-page application. Every page edits what it shows through forms, every pending change reads as a sentence before it is applied, and Advanced mode shows the set and delete lines behind each one.
The installer — wheelhouse-install and its unattended path, plus the OPNsense importer that turns a config.xml into VyOS commands and a report.
The console tools — wheelhouse-rescue, which the medium's rescue boot entry lands on, and wheelhouse-support, which collects a redacted diagnostic archive. Both are Wheelhouse programs that read and write the agent's own files and drive the base's CLI from outside it.
The app catalogue — container entries declared in the router's own configuration tree, and three built-in feature modules.
The licence — offline-verified subscription keys gating the write plane only.

None of it is derived from VyOS or from any other GPL work.

Where the boundary sits#

agent/ and ui/ are separate processes from every GPL component. The agent links against no VyOS code and copies none. No file in the repository is derived from vyos-1x, FRR, Kea, pdns-recursor, nftables or the kernel. Four rules keep it that way, in order of importance:

No GPL or AGPL code is copied into agent/ or ui/. Not a function, not a parser, not a constant table. Where behaviour is needed that exists in a GPL project, it is called or reimplemented from its documented behaviour.
Permissive only for compiled-in dependencies: MIT, BSD-2/3, ISC, Apache-2.0. Anything weak-copyleft needs a recorded decision first; anything strong-copyleft is out — Third-party licences.
Patches to GPL components get published. Wheelhouse patches exactly one GPL file today, in the build tooling — see below.
The trademark is separate from the licence. See Trademarks.

The GPL parts of a Wheelhouse image are ordinary, unmodified upstream packages, and you can obtain their source — Corresponding source. The agent, the UI and the installer are proprietary and their source is not offered — The Wheelhouse licence.

Which base an image is built from#

Images are self-built. The build clones vyos-build, resets it to a pinned commit, applies the branding, drops the Wheelhouse .deb into packages/ and runs upstream's own build-vyos-image inside upstream's own build container.

What	Value
Repository	`https://github.com/vyos/vyos-build` (`VYOS_BUILD_REPO`)
Branch	`rolling` (`VYOS_BRANCH`). Upstream renamed `current` to `rolling` in 2026
Commit	Pinned in the script: `b365961c7513f05e74126924f48873776ed47c1d`. `VYOS_COMMIT=head` follows the branch instead and prints a warning that the result must not be shipped
Build container	`vyos/vyos-build:rolling`, with the digest actually pulled recorded in the source record
Flavor	A VyOS build flavor file, rendered with the version and the base substituted in

The base is a rolling release with no snapshots: the apt repository it installs from moves, so two builds a week apart are not the same image. The exact package versions of a given build are recorded in SOURCES-<version>-amd64.txt and in /var/lib/dpkg/status on the image itself. That record, not the pin, is what identifies a build.

The base version is written into /etc/os-release as VYOS_VERSION, in the form <branch>@<commit>. Three places on a running router will tell you what you are on:

bash

cat /etc/os-release            # NAME, ID=wheelhouse, ID_LIKE="vyos debian", VYOS_VERSION
show version                   # VyOS' own op-mode command

and the console banner's last lines, which print Built on VyOS <version> above every login prompt.

The one GPL file Wheelhouse changes#

Not in the image — in the build tooling. The image build applies three substitutions to vyos-build's own scripts/image-build/build-vyos-image:

--iso-application "VyOS"   ->  "Wheelhouse"
--iso-volume "VyOS"        ->  "WHEELHOUSE"
hostname=vyos              ->  hostname=wheelhouse

Each substitution asserts that the string it replaces is really there and fails the build if it is not. The resulting diff is published with every release as vyos-build-wheelhouse-<version>-amd64.patch, is named in the source record, and the build fails if that diff comes out empty. Everything else Wheelhouse contributes to the image is added as new files — the flavor, two branding hooks, the boot splash, the documents under /usr/share/doc/wheelhouse/ and the agent package — and none of them is derived from upstream's.

What the image changes about identity#

Change	Why
`/etc/os-release` becomes Wheelhouse's, keeping `ID_LIKE="vyos debian"` and `VYOS_VERSION`	So monitoring, `hostnamectl` and Ansible facts see both the product and the base
The boot splash, the boot menus and the console banner are Wheelhouse's own	None of VyOS' artwork is redistributed in the image
Both bootloaders gain Rescue an installed Wheelhouse system, cloned from each live entry and appended last	Upstream's menu has no rescue path to rename, so this is added rather than rewritten. It is appended so that nothing's default changes, and the clone drops `quiet` because its messages are the reason it exists
The login banner is set in the default configuration	Without it, upstream's template renders its own welcome, logo and support links onto a machine sold as Wheelhouse. The upstream credit stays, one line, at the bottom
`/usr/share/vyos/EULA` becomes a symlink to `/usr/share/doc/wheelhouse/TERMS.txt`	A release build otherwise installs VyOS Inc.'s commercial end-user agreement, which governs nothing you bought here. `show license` reads that path, so it prints the Wheelhouse terms
VyOS' Secure Boot MOK certificate is removed from `/var/lib/shim-signed/mok`	It is a public certificate rather than a key, and it is not enrolled in firmware, but it is a trust anchor belonging to somebody else

Removing those two files strips no required notice. Every licence and every copyright file stays exactly where the packages put it, under /usr/share/doc/ — Third-party licences.

The branding hook asserts ID=wheelhouse in /etc/os-release afterwards and fails the build if the override stopped winning, so the failure mode is a build that stops rather than an image that calls itself something it is not.

Platform gaps#

What the configuration tree cannot express, with the date it was checked and what Wheelhouse does about it today.

Committing nat static through the HTTP API stops the API process

Seen 2026-09-02 on this build's base: a 1:1 NAT rule committed through VyOS' HTTP API takes down vyos-http-api; the CLI commits the same lines without complaint. Not reproduced on 0.6.2 (2026-09-04), which committed four shapes cleanly — but Wheelhouse cannot tell an affected build from an unaffected one without running the commit that breaks the affected one. So Wheelhouse does not write nat static: since 0.9.1 the NAT page builds a 1:1 mapping as a destination and source NAT rule pair, which the API commits like any other rule and the Commit Bar applies. A nat static rule made elsewhere is listed as a read-only mapping. The agent refuses nat static at every door that reaches a commit — /api/stage, /api/fleet/{id}/stage, /api/configure, /api/reconcile with apply=true, /api/commit, /api/fleet/{id}/configure and /api/fleet/{id}/commit — so nothing in the product can reach that commit path by accident.

CAKE cannot attach to ingress, and has no overhead compensation

qos interface <if> ingress takes a limiter and nothing else, so CAKE reaches the download only through an IFB device. And there is no DOCSIS or ATM overhead compensation anywhere in the tree — no docsis, overhead, mpu or atm leaf under qos policy cake — which is why the kernel keeps reporting raw overhead 0.

What the tree does express, and the QoS page stages: an upload and a download rate on each interface, a VLAN included. Upload is a CAKE policy on the interface's egress. The download takes either route the platform has — Policing, a limiter on qos interface <if> ingress, or CAKE shaping through an IFB the agent's planner chooses and reuses. CAKE takes bandwidth, flow isolation, RTT, ack-filter, flow-isolation-nat and no-split-gso, and the page says whether the kernel is running what the configuration asks for. The agent reads tc qdisc show; it does not program tc directly.

No UPnP or NAT-PMP in the base

VyOS has no UPnP. The pinned base has no service upnp configuration node at all — not an unset one, an absent one — and no miniupnpd package installed, so this is not a feature waiting to be switched on. No credible published container image exists for miniupnpd either; the available ones are unaudited personal builds, refused on principle for a privileged host-network daemon.

Wheelhouse provides it instead. The agent answers UPnP and NAT-PMP itself and writes each mapping as a port forward and a firewall rule, applied to the configuration like any other change. It is set up on the UPnP page, is off until an administrator turns it on, and opens IPv4 ports only. The Companions page lists it as Wheelhouse's own service rather than asking the base about a node it does not have.

Trademarks, briefly#

VyOS is a registered trademark of Sentrium S.L. Wheelhouse is not affiliated with, endorsed by, certified by or supported by the VyOS project or Sentrium S.L. The images are self-built and rebranded per upstream's trademark policy with attribution intact, and support for this product comes from Wheelhouse — do not ask the VyOS project about it. The full position is on Trademarks.