Wheelhouse and VyOS#
Wheelhouse is built on VyOS, which is GPL-licensed, on a Debian
base. The router underneath is VyOS: its configuration tree, its commit and
commit-confirm, its revision archive, its HTTP API, and the Linux networking stack it
integrates. Wheelhouse adds a control-plane agent, a web UI, accounts and roles, an
audit log, an app catalogue, a desired-state engine and an installer, and drives VyOS
as a separate program over its documented API. Knowing which half you are looking at
makes the rest of this documentation easier to read, and it is the reason a claim on
one page points at VyOS and a claim on another points at agent/.
Which half is which#
| From the base | From Wheelhouse |
|---|---|
The configuration tree, and set / delete as the way to change it | The staging area and the Commit Bar — the change set as an object you can see |
commit, commit-confirm and the reboot that makes it safe | The button that arms it, the countdown, and the flagging of paths that warrant it |
The revision archive and show system commit | The history screen, the per-revision diff view and POST /api/rollback |
The Linux kernel, nftables, conntrack, tc, WireGuard, veth and VLAN | The screens over them, and the state-beside-intent comparisons |
FRR, Kea, pdns-recursor, strongSwan, OpenVPN, Suricata, Podman | The pages that read and write their configuration subtrees |
| The HTTP API the agent talks to | wheelhouse-agent: caching, parsing, staging, accounts, audit, metrics |
| — | Accounts, roles, sessions, TOTP, OIDC, API tokens, the audit log |
| — | The app catalogue and the apps-are-config model on top of set container |
| — | The desired-state engine and the reconcile loop |
| — | The installer, the image build, the branding and the release pipeline |
| — | The licence |
The transactional configuration model that this whole product is built around is VyOS', not ours. That debt is worth stating plainly rather than leaving implied.
Where the boundary is drawn#
agent/ and ui/ are separate programs from every GPL component. The agent
speaks to the router over its documented HTTP API and its op-mode commands; it 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. The rules, in the order
docs/licenses.md puts them:
- No GPL or AGPL code is copied into
agent/orui/— not a function, not a parser, not a constant table. Behaviour that exists in a GPL project is called, or reimplemented from its documented behaviour. - Compiled-in dependencies are permissive only (MIT, BSD, ISC, Apache-2.0). Anything weak-copyleft needs a recorded decision first; strong-copyleft is out.
- Patches to GPL components are published.
- The trademark is separate from the licence. Shipped images are self-built and rebranded per upstream's trademark policy, with attribution intact.
The agent has five direct dependencies and everything else is the Go standard library;
they are listed with their versions and licences in
docs/licenses.md and can be re-derived with
cd agent && go list -m all.
When the base cannot express something#
Some things a router needs have no node in the configuration tree, or have one that does not behave as its shape suggests. This documentation calls those platform gaps, states them as facts with the workaround, and never as a complaint. Four that are recorded in the tree, with what Wheelhouse actually does about each:
| Gap | What Wheelhouse does |
|---|---|
Wildcard DNS records: records a * fails validation; an apex @ works | The dnsmasq catalogue app covers wildcard and split-horizon DNS. It is one container answering three documented gaps (docs/apps.md). |
| Per-host DHCP option overrides, and RFC 4578 architecture-conditional PXE | The same dnsmasq entry. |
CAKE: egress only; no ack-filter, no DOCSIS overhead compensation, no NAT flow isolation; attaching it to ingress is rejected | The QoS editor stages what the tree does express — a qos policy cake with bandwidth, flow isolation and RTT, attached as egress on one interface — and shows the qdisc the kernel installed beside it. |
Committing nat static through this base's HTTP API stops the API process; the CLI accepts the same lines | The 1:1 NAT editor is switched off, with that reason on the page. The table still reads rules made from the CLI. |
Living on a rolling base#
The base is a rolling release, and its configuration syntax moves: mac-address
became mac for Kea static mappings, and that change reached the product before it
reached anyone's notes. Two things follow.
- Images are pinned and self-built. Each release is built from
vyos-buildat a named commit, and every release carries aSOURCES-<version>.txtrecording that commit, the container it was built in and the version of every installed package. - Behaviour is verified against a live router, with dates. The API facts this
product depends on were checked on a bench and are recorded with the date they were
checked (
docs/api-cookbook.md). Where this documentation states a platform behaviour, it carries the same date, because a rolling base can change it.
Saying so on the box#
The attribution is not confined to a documentation page.
- The console banner shown above every login prints the Wheelhouse version and the host
name, the web UI addresses, the path to the licence texts — and, at its foot,
Built on VyOS <version>(packaging/console-banner.sh). - The post-login banner the router itself renders says
Built on VyOS <version> (GPL). Corresponding source: /usr/share/doc/wheelhouse(packaging/firstboot.sh). - The product's own About page says the same inside the web UI.
/usr/share/doc/wheelhouse/on a running router carries the third-party licence text, the source record and the written offer.
Both banners resolve the base version from /etc/os-release rather than from the
router's own version file, because on a rebranded image that file holds Wheelhouse's
version — reading it there credited the base with a version that was never a VyOS
release. Where the base version cannot be resolved, the credit prints without one,
never a wrong one.
See also#
- Built on VyOS — the attribution page.
- About Wheelhouse — the licence boundary and how to get the corresponding source.
- The configuration tree — the part of the model that is VyOS'.
- What the agent asks the router — the API relationship.
- The console banner — what it prints, line by line.
- Trademarks.
- Third-party licences and the source offer.
Checked against#
docs/licenses.md ·
docs/apps.md ·
docs/api-cookbook.md ·
agent/go.mod ·
packaging/firstboot.sh ·
packaging/console-banner.sh ·
packaging/iso/build-iso.sh ·
README.md ·
PLAN.md §3 §5