Wheelhouse docs

Reference#

This section is the enumerable half of the documentation: what exists, what it is called, what it defaults to. Nothing here explains why — the concept pages do that, and the task guides show the order to do things in. A page here is a table you come back to at 2am with a specific question, plus the command that regenerates the table from the tree so you can check it against the version you are actually running.

Every list is derived from one place in the source, and every page names that place in its Checked against line. If a number here disagrees with your router, the source file wins and this page is stale — re-derive it with the command on the page and tell us which one moved.

The agent#

PageWhat it lists
wheelhouse-agentThe binary, its three subcommands, and how flags and a subcommand interleave on one command line.
Every flagAll 51 flags with their defaults and what each one changes.
Environment variablesThe six the agent reads, the one the UI build reads, and why the file forms are preferred.
Exit codesWhat 0, 1, 2 and a killed process mean, per subcommand and per script.
Log lines worth alerting onThe exact lines the agent writes that should page somebody, and what each one means.

The HTTP API#

PageWhat it lists
The HTTP APIBase URL, content type, body limits, security headers, and the shape of an error.
AuthenticatingSession cookie plus X-Wheelhouse-CSRF from a browser, Authorization: Bearer wh_… from a script.
Endpoint indexEvery route the agent registers, with method, role, licence requirement and description.
Role matrixWhich of viewer / operator / admin each route needs, and which also need a licence.
What a read hidesredactSecrets, the leaf names it blanks, and the endpoints that wear it.
The telemetry streamGET /api/stream: the WebSocket, its two frame types, and same-origin enforcement.
Status codesWhat 401, 402, 403, 409, 501 and 502 mean on this API specifically.
Prometheus metricsEvery series, its labels, and when a series is absent entirely.

Files, ports and units#

PageWhat it lists
Files and directoriesEvery path the product creates or reads, with modes, on both install layouts.
Ports and listenersWhat listens where after an install, bound to what, reachable from where.
systemd unitsThe four units and one timer, what each does and when it runs.
What first boot doesMinting the router API key, enabling REST, pinning the router API to loopback.
The console bannerEvery line it prints, how often it is redrawn, and why the getty restarts.
Identifying the system/etc/os-release, VYOS_VERSION, and what show version reports.

Configuration formats#

PageWhat it lists
The desired-state fileFormat sniffing, the config-tree shape, what a key with no value means, and the exit codes of plan.
Answer-file keysEvery KEY=VALUE the installer accepts, with defaults.
Seed cloud-config keysEvery key under wheelhouse: in a seed, and what each becomes.
Where the installer looks for a seedThe four sources in order, the kernel parameters, and the once-per-boot rule.
Audit entriesEvery field an entry carries, what is recorded, what is not, and retention.
Licence keys and statesThe WHL1.… shape, the seven states, expiry and grace.
Channel index formatstable.json / beta.json: every field, and how to build a download URL from one.

The catalogue#

PageWhat it lists
Catalogue schemaEvery field an entry may declare.
The catalogueAll 38 entries by category, with image, ports, volumes and integrations.
Hint placeholdersThe four placeholders, and what a router that cannot fill one does.

Packaging and images#

PageWhat it lists
The .debWhat it installs, where, and what postinst does on an upgrade.
The ISOHow the image is built, the flavor, the branding hooks, and what ships in /usr/share/doc/wheelhouse/.

Tools#

PageWhat it lists
ToolsThe five programs that ship beside the agent.
opnsense-import.pyEvery option, everything it translates, everything it only names in the report.
wheelhouse-seed.pyBuilding a seed image or directory, and handling the passwords on it.
install.shThe lab installer: subcommands, the A/B binary swap, the health check.
sign.shBuilding and verifying a manifest of a binary and its UI assets.
check-images.pyChecking, and pinning, the catalogue's container images.

Cross-cutting tables#

PageWhat it lists
Which page writes which subtreeEvery screen in the web UI mapped to the configuration subtree it owns.
The commands Wheelhouse runsThe op-mode reads the agent depends on, and the config paths it writes.
TroubleshootingSymptom, then what to check.
GlossaryEvery term this documentation uses in a particular way, defined once.

How to re-derive a list#

Each page carries the command for its own table. The five that come up most:

bash
# every route the agent registers
grep -o 'mux.HandleFunc("[A-Z]* [^"]*"' agent/main.go

# every flag, with its default and help text
grep -E '^\tflag\.(String|Bool|Int|Duration)Var' agent/main.go

# every metric series name
grep -o 'wheelhouse_[a-z_]*' agent/metrics.go | sort -u

# every answer-file key the installer honours
grep '^ANSWER_KEYS=' packaging/wheelhouse-install

# every catalogue entry
python3 -c 'import json;print("\n".join(a["id"] for a in json.load(open("agent/catalog.json"))["apps"]))'

Run them against the tag you are running, not against main.

See also#

Checked against#

agent/main.go, agent/metrics.go, agent/catalog.json, packaging/wheelhouse-install, docs/deploy.md, docs/README.md.

Updated 2026-09-02 reference