Environment variables#

Every environment variable the agent reads is a default for a flag. Nothing is configured by environment alone: a flag given on the command line wins. Five of them carry a secret, and each has a -file counterpart. A process's environment is readable through /proc by anyone who can read the process, and a systemd unit that sets one is a world-readable file with a credential in it.

What the agent reads#

Variable	Sets the default for	Holds
`VYOS_API_KEY`	`--api-key`	The router's own API key. Root-equivalent on that router.
`WHEELHOUSE_ADMIN_TOKEN`	`--admin-token`	The break-glass Bearer token: admin role, no account behind it.
`WHEELHOUSE_LICENSE`	`--license-key`	A licence key.
`WHEELHOUSE_INITIAL_PASSWORD`	`--initial-admin-password`	The first-run admin password. Read only when the state file has no users.
`WHEELHOUSE_OIDC_ISSUER`	`--oidc-issuer`	The identity provider's issuer URL. Not a secret, but it is the one that decides whether single sign-on is on at all.
`WHEELHOUSE_OIDC_CLIENT_ID`	`--oidc-client-id`	The OIDC client id.
`WHEELHOUSE_OIDC_SECRET`	`--oidc-client-secret`	The OIDC client secret.

Seven rows: six secrets and one identifier. To re-derive the list:

bash

grep -o 'os.Getenv("[A-Z_]*")' agent/main.go | sort -u

What the file forms do instead#

Instead of	Use	Missing file behaviour
`VYOS_API_KEY`	`--api-key-file`	Fatal. Exit 2.
`WHEELHOUSE_ADMIN_TOKEN`	`--admin-token-file`	Warns and continues with no break-glass token.
`WHEELHOUSE_LICENSE`	`--license-key-file`	Warns and continues unlicensed.
`WHEELHOUSE_INITIAL_PASSWORD`	`--initial-admin-password-file`	Warns and continues; the agent generates a password.
`WHEELHOUSE_OIDC_SECRET`	`--oidc-client-secret-file`	Warns and continues; startup then fails validation if an issuer is configured.

A file that exists but is group- or world-readable is always fatal, whichever flag named it:

api-key-file (/config/wheelhouse/api-key) is mode 644; it must not be readable by
group or other (chmod 600)

An empty or whitespace-only file leaves the flag's value alone rather than blanking it.

The build-time variable#

Variable	Read by	Effect
`VITE_WHEELHOUSE_VERSION`	The UI's Vite build	Stamps a version string into the bundle. It is the UI's second source: the `product` block on `GET /api/system` is the box's own answer and wins over it. There is no hardcoded fallback constant. An unstamped build with no agent block reports `unknown`.

The agent's own version is compiled in, not read from the environment. The release build sets it with a linker flag:

bash

go build -trimpath -ldflags="-s -w -X main.version=1.2.3" -o wheelhouse-agent .

The same technique overrides the licence public keys compiled into the binary (-X main.licensePublicKeys=<kid>:<base64>); see Licence keys and states.

Variables the other programs read#

These belong to the build and developer scripts. None of them runs on a router.

Variable	Read by	Meaning
`DEB`	`packaging/iso/build-iso.sh`	Required. The `.deb` to bake into the image.
`VERSION`	`build-iso.sh`	Image version; default `dev`.
`BUILD_DIR`	`build-iso.sh`	Working directory; default `/srv/wheelhouse-build`.
`VYOS_BRANCH`	`build-iso.sh`	`vyos-build` branch and container tag; default `rolling`.
`VYOS_BUILD_REPO`	`build-iso.sh`	Where `vyos-build` is cloned from; default the upstream GitHub repository.
`VYOS_COMMIT`	`build-iso.sh`	The pinned `vyos-build` commit. `head` follows the branch instead and prints a warning that the result must not be shipped.
`VYOS_BUILD_IMAGE`	`build-iso.sh`	The build container; default `vyos/vyos-build:$VYOS_BRANCH`.
`BUILD_BY`	`build-iso.sh`	The `--build-by` string recorded in the image.
`SOURCE_DATE_EPOCH`	`packaging/build-deb.py`	Timestamp stamped into every archive member, for a reproducible `.deb`.
`RELEASE_SIGNING_KEY`	`install/sign.sh`	The GPG key to sign with. No key has been generated; without it, `sign` refuses rather than inventing one.
`GPG_PASSPHRASE`	`sign.sh`	Enables batch signing on a runner.
`WHEELHOUSE_PUBKEY`	`sign.sh`	Armoured public key to verify against, instead of the caller's keyring.
`REQUIRE_SIGNATURE`	`sign.sh`	Set to `1` to make `verify` fail when nothing is signed.
`API_URL`, `API_KEY`, `ADMIN_TOKEN`, `BIND_ADDR`, `LOCAL_BIN`	`install/install.sh`	Defaults for the developer installer's flags.