How Wheelhouse works#
Wheelhouse is a web UI and an HTTP API in front of a router whose configuration is a
tree, not a database of forms. Everything else in this documentation follows from
that. A change is a set or a delete against a path in that tree; changes collect
in one working set; one commit applies the whole set at once; the commit becomes a
numbered revision you can look at and go back to. This section explains each link in
that chain once, so that the manual and the guides can name a
concept instead of re-explaining it.
The road a change travels#
Nothing on any page applies itself. An editor renders the exact commands it would run,
hands them to the staging area, and stops. The Commit Bar is the only component that
calls POST /api/commit — ui/src/components/CommitBar.tsx,
and the rule is written down in docs/ui.md as the first of the
four rules every page follows.
That single road is what makes the rest possible. Because a change is a list of commands before it is a commit, it can be shown, edited, copied into a terminal, abandoned, or committed with the router's own rollback timer armed.
The pages in this section#
| Page | The idea |
|---|---|
| The configuration tree | Nodes, tag nodes and values; why every screen names the subtree it owns. |
| Every click shows its commands | Why the UI renders set and delete before it does anything, and how to use that. |
| Staging: the working set | Where a change waits, why the queue lives on the agent rather than in your tab, and what may enter it. |
| The Commit Bar | The one component that commits, and how it decides a change is dangerous. |
| Commit-confirm | Arm a window, confirm it, or the router reboots into the previous configuration. |
| Revisions and rollback | Every commit is archived; rolling back loads an archived revision and commits it. |
| State, intent and drift | What the kernel is doing, beside what the configuration declares, and every place the two are compared. |
| Desired state | One file describes the router; one engine turns the gap into operations. |
| Apps are configuration | An add-on is a container declared in the config tree, so installing one is a diff you review. |
| Read plane, write plane, admin plane | Three roles, enforced by the agent on every route. |
| Accounts, sessions and tokens | The three kinds of principal, what proves each one, and what a second factor covers. |
| The audit log | Who changed what, from where — and how that differs from the journal and the commit history. |
| What the licence gates | Reads never need a licence; every mutating route answers 402 without one. |
| What the agent asks the router | Every API call forks a shell on the router, and everything about the cache follows from that. |
| On-router, off-router, fleet | Three ways the agent runs, and what changes in each. |
| Wheelhouse and VyOS | What comes from the base, what Wheelhouse adds, and where the boundary is drawn. |
Why a config model rather than a database of forms#
The router underneath Wheelhouse is VyOS, and its configuration is a single transactional tree. That gives four properties an appliance built around per-page forms cannot offer, because they are properties of the configuration system rather than of the user interface:
- A change set exists as an object. It can be listed, printed, reviewed and thrown away before anything happens. A form that writes on save has no such object to show you.
- A commit is atomic. Either every command in the set applies, or none does. The
agent sends the whole working set as one array to the router's
/configureendpoint —agent/staging.goToConfigurePayload. - The previous configuration is still there. The router archives each commit, so "go back" is loading revision 1, not restoring a backup.
- The failure path is a reboot into a known-good configuration, not a hope that the UI can still reach you. That is what commit-confirm buys.
None of those four is Wheelhouse's invention. They are VyOS', and Wheelhouse is built on VyOS — see Wheelhouse and VyOS. What Wheelhouse adds is the staging area, the Commit Bar, the accounts and roles, the audit log, the app catalogue, the installer and the web UI that makes all of it visible.
What this section is not#
It is not a tour of the screens — that is the manual: Network, Security, VPN and accounts and Services, monitoring and system — and it is not a set of instructions. Each page here answers "what is this, why does it exist, what does it cost, and where do I see it", and then points at the page that tells you what to press.
See also#
- What Wheelhouse is — the same ground in one page, for someone deciding whether to install it.
- The manual — a page per screen: Network, Security, VPN and accounts, Services, monitoring and system.
- Agent endpoints — the API the UI itself consumes.
- About Wheelhouse — the licence boundary and the source offer.
Checked against#
docs/ui.md ·
PLAN.md §4 ·
agent/staging.go ·
agent/main.go ·
ui/src/components/CommitBar.tsx