Every flag#

wheelhouse-agent registers 51 flags. Every subcommand shares the whole set, so a flag that means nothing to plan is accepted and ignored rather than refused.

Re-derive the list for the version you are running:

bash

grep -E '^\tflag\.(String|Bool|Int|Duration)Var' agent/main.go

Router connection#

Flag	Default	What it does
`--api-url`	`https://127.0.0.1`	Base URL of the router's own HTTP API. A trailing slash is trimmed. On an appliance this is loopback, because first boot pins the router API to loopback.
`--api-key`	`$VYOS_API_KEY`	The router API key. Root-equivalent on that router. Prefer the file form.
`--api-key-file`	—	File holding the key. Required to exist when given: a missing file here is fatal, unlike the other four secret files.
`--demo`	`false`	Start with no router credentials at all. Every router read then fails; the UI still loads. Also disables the cache primer.

Either --demo, or both a non-empty --api-url and a non-empty API key, are required. Without them the agent logs either --demo or both --api-url and --api-key are required and exits 2.

Listener#

Flag	Default	What it does
`--addr`	`127.0.0.1:8090`	Listen address. The shipped systemd unit overrides this to `0.0.0.0:8443` — every interface, including the WAN.
`--ui-dir`	—	Directory of built UI files. Empty means no `GET /` route at all: the API answers, the browser gets a 404. The package installs the UI at `/usr/share/wheelhouse/ui`.
`--trust-proxy`	`false`	Trust `X-Forwarded-For` and `X-Forwarded-Proto`. Only behind a reverse proxy you control — without it, a client could forge its own address into the audit log and around the per-address login rate limit. The last element of the header is the one used.
`--metrics-public`	`false`	Serve `GET /metrics` with no authentication. Off by default, where the route needs the viewer role.

Data and state#

Flag	Default	What it does
`--data-dir`	`/config/wheelhouse`	Everything the agent persists: `state.json`, `audit.jsonl`, the self-signed certificate, `initial-password`. Created at mode 0700 if missing. On VyOS, `/config` survives an image upgrade and `/var/lib` does not.
`--fleet-config`	—	JSON file listing other routers. Loaded whatever the licence says; the fleet endpoints answer `402` until a licence whose plan includes `fleet` is held. The file must be mode 0600 or the agent exits 1.

Only one agent may hold a data directory at a time. A second one exits 1 with another agent is running against this data dir.

TLS#

Flag	Default	What it does
`--tls-cert`	—	Certificate file. Must be given together with `--tls-key`; one without the other is a startup error.
`--tls-key`	—	Private key file.
`--tls-self-signed`	`false`	Generate `agent.crt` / `agent.key` in the data directory when `--tls-cert` is not set and no usable pair is already there.

The generated certificate is a server leaf, not a CA: P-256 ECDSA, 398 days, DigitalSignature + ServerAuth, IsCA: false, with SANs for the host name, <host>.local, localhost, 127.0.0.1, ::1 and every non-loopback address on the box. An existing certificate is replaced on sight if it is unreadable, if it was generated as a CA, or if it expires within 30 days.

Serving on a non-loopback address with no certificate logs a warning naming the three fixes. See Ports and listeners.

Authentication and the first account#

Flag	Default	What it does
`--admin-token`	`$WHEELHOUSE_ADMIN_TOKEN`	Break-glass Bearer token, admin role, no account behind it. Prefer the file form.
`--admin-token-file`	—	File holding it. A missing file degrades to "no break-glass" with a warning rather than aborting startup.
`--initial-admin`	`admin`	User name created on the first start with an empty state file.
`--initial-admin-password`	`$WHEELHOUSE_INITIAL_PASSWORD`	Password for that account. Empty means the agent generates one, logs it once and writes it to `<data-dir>/initial-password` at 0600.
`--initial-admin-password-file`	—	File holding it; overrides the flag.

All three initial-account flags are read only when the state file has no users. Any non-empty password is accepted; an empty one, or one over 1024 characters, is refused. The account is flagged must change password either way.

Licensing#

Flag	Default	What it does
`--license-key`	`$WHEELHOUSE_LICENSE`	The licence key. A key given here is also saved into the state file, so the next start without the flag still holds it.
`--license-key-file`	—	File holding it.
`--license-server`	`https://license.rhymelikedi.me`	Where the daily refresh goes. An empty value disables the refresh entirely and runs on the offline path.

Without a usable licence every mutating endpoint answers 402 and every read keeps working. See Licence keys and states.

Single sign-on#

Everything here is optional. An agent with no issuer keeps password, TOTP, token and break-glass logins.

Flag	Default	What it does
`--oidc-issuer`	`$WHEELHOUSE_OIDC_ISSUER`	Issuer URL, e.g. `https://auth.example.com/application/o/wheelhouse/`. Must be an absolute `http(s)` URL.
`--oidc-client-id`	`$WHEELHOUSE_OIDC_CLIENT_ID`	Client id.
`--oidc-client-secret`	`$WHEELHOUSE_OIDC_SECRET`	Client secret. Prefer the file form.
`--oidc-client-secret-file`	—	File holding the secret.
`--oidc-redirect-url`	derived per request	The exact `/api/oidc/callback` URL registered at the provider. When given it must be a full URL ending in `/api/oidc/callback`.
`--oidc-scopes`	`openid profile email groups`	Space-separated scopes to request.
`--oidc-username-claim`	`preferred_username`	Claim used as the local user name when provisioning: `preferred_username`, `email`, `name` or `sub`.
`--oidc-groups-claim`	`groups`	Claim holding group membership.
`--oidc-admin-groups`	—	Comma-separated groups mapped to the admin role. Empty means no group mapping at all.
`--oidc-operator-groups`	—	Comma-separated groups mapped to the operator role.
`--oidc-default-role`	`viewer`	Role for a provisioned user outside every mapped group. Must be `viewer`, `operator` or `admin`.
`--oidc-provision`	`true`	Create a local account on the first sign-on for an unknown identity.
`--oidc-link-by-email`	`false`	Link an identity to an existing account by email — and only when the provider asserts `email_verified`.
`--oidc-label`	`Authentik`	Provider name shown on the login screen.
`--oidc-ca-file`	—	PEM root CA to trust for the issuer instead of the system trust store.
`--oidc-post-logout-redirect`	—	Registered post-logout URI to send the browser to at the provider.

Single sign-on is "configured" only when both --oidc-issuer and --oidc-client-id are set. The agent exits 2 at startup on any of these:

--oidc-issuer without --oidc-client-id, or the reverse;
an issuer that is not an absolute http(s) URL;
a configured provider with no client secret;
a --oidc-redirect-url that does not end in /api/oidc/callback;
an invalid --oidc-default-role;
--oidc-provision together with --oidc-username-claim=sub, which would name every account after a UUID.

When it validates, the agent logs one line at start naming the issuer, client id, redirect URI, provisioning and default role. Compare it with the registration at the provider.

Desired state (`plan` and `apply`)#

Flag	Default	What it does
`--file`	`<data-dir>/agent.yaml`	The desired-state document. JSON or YAML, chosen by what the bytes look like rather than by the extension.
`--full`	`false`	Full mode: also emit `delete` for live nodes the file does not declare.
`--json`	`false`	With `plan`: emit a JSON document instead of command lines.
`--commit`	`false`	With `apply`: commit instead of staging. Requires `--confirm-minutes`.
`--confirm-minutes`	`0`	The commit-confirm window for `--commit`. `apply --commit` refuses to run at 0.
`--agent-url`	—	With `apply`: the running agent to stage through, e.g. `https://127.0.0.1:8443`. Needs `--admin-token` or `--admin-token-file`.

The reconcile loop#

Off unless --reconcile-file is set. It is a writer, so it obeys the same licence gate as the Commit Bar and pauses without one.

Flag	Default	What it does
`--reconcile-file`	—	Keep the router aligned with this desired-state file. Empty means the loop never runs.
`--reconcile-mode`	`stage`	`stage` puts the difference in the Commit Bar and waits for a person; `commit` applies it. Any other value is a startup error (exit 2).
`--reconcile-interval`	`60s`	How often the loop re-diffs. Values below the 10 s floor are clamped, with a warning naming what you asked for.
`--reconcile-delay`	`15s`	How long after start the first pass waits.
`--reconcile-confirm`	`2`	Commit-confirm minutes used in commit mode. At 0 or below, the loop commits without a confirm window.
`--reconcile-full`	`false`	Run the loop in full mode, which deletes what the file does not declare.

Diagnostics#

Flag	Default	What it does
`--log-level`	`info`	`debug`, `info`, `warn` or `error`. An unparseable value silently becomes `info`.
`--version`	`false`	Print `wheelhouse-agent <version>` and exit 0. Identical to the `version` subcommand.

What the shipped unit passes#

The appliance's systemd unit uses ten of these and nothing else:

--api-url https://127.0.0.1
--api-key-file /config/wheelhouse/api-key
--admin-token-file /config/wheelhouse/admin-token
--license-key-file /config/wheelhouse/license-key
--addr 0.0.0.0:8443
--tls-self-signed
--ui-dir /usr/share/wheelhouse/ui
--data-dir /config/wheelhouse
--log-level info

It sets no OIDC flags, so writing an oidc-secret file on its own configures nothing; turning single sign-on on means a drop-in that repeats ExecStart with the --oidc-* flags added. See systemd units.