Reference#

What exists, what it is called, what it defaults to. The concept pages explain the model and the guides give the order to do things in; the pages here are tables, each with the command that regenerates it from the source so you can check it against the version you are running.

If a number here disagrees with your router, your router is right. Re-derive the list with the command on the page and report which one moved.

The agent#

Page	What it lists
`wheelhouse-agent`	The binary, its three subcommands, and how flags and a subcommand interleave on one command line.
Every flag	All 51 flags with their defaults and what each one changes.
Environment variables	The six the agent reads, the one the UI build reads, and the file form of each secret.
Exit codes	What 0, 1, 2 and a killed process mean, per subcommand and per script.
Log lines worth alerting on	The exact lines the agent writes that should page somebody, and what each one means.

The HTTP API#

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

Files, ports and units#

Page	What it lists
Files and directories	Every path the product creates or reads, with modes, on both install layouts.
Ports and listeners	What listens where after an install, bound to what, reachable from where.
systemd units	The four units and one timer, what each does and when it runs.
What first boot does	Minting the router API key, enabling REST, pinning the router API to loopback.
The console banner	Every 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#

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

The catalogue#

Page	What it lists
Catalogue schema	Every field an entry may declare.
The catalogue	All 40 entries by category, with image, ports, volumes and integrations.
Hint placeholders	The four placeholders, and what a router that cannot fill one does.

Packaging and images#

Page	What it lists
The `.deb`	What it installs, where, and what `postinst` does on an upgrade.
The ISO	How the image is built, the flavor, the branding hooks, and what ships in `/usr/share/doc/wheelhouse/`.

Tools#

Page	What it lists
Tools	The five programs that ship beside the agent.
`opnsense-import.py`	Every option, everything it translates, everything it only names in the report.
`wheelhouse-seed.py`	Building a seed image or directory, and handling the passwords on it.
`install.sh`	The developer installer: subcommands, the A/B binary swap, the health check.
`sign.sh`	Building and verifying a manifest of a binary and its UI assets.
`check-images.py`	Checking, and pinning, the catalogue's container images.

Cross-cutting tables#

Page	What it lists
Which page writes which subtree	Every screen in the web UI mapped to the configuration subtree it owns.
The commands Wheelhouse runs	The op-mode reads the agent depends on, and the config paths it writes.
Troubleshooting	Symptom, then what to check.
Glossary	Every 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, with its role and licence gate
wheelhouse-agent endpoints

# 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.