The developer install#

install/install.sh puts a Wheelhouse agent on a host that can reach an existing VyOS router's HTTP API. It is the development and lab path, not the product: different port, different file layout, different place for secrets, and no support. It is documented here for one reason — almost every "the address in the documentation does not work" question comes from confusing this with an appliance, so knowing which one you are looking at is worth a page.

Telling the two apart#

Anything you read that names port 8090 or /etc/wheelhouse is describing this path. On the appliance, read 8443 and /config/wheelhouse.

Note the one row that is the same on both: agent state lives in /config/wheelhouse either way, because on VyOS /config is the partition that survives an image upgrade and /var/lib is not. Nothing on an appliance reads /etc/wheelhouse, so a secret written there by this script is a file the agent will never open.

What it needs#

• A VyOS 1.4 or newer router reachable over its HTTP API.
• That router's API key, from show service api-key.
• Either a pre-built agent binary and ui/dist, or Go 1.22+ and Node.js 20+ to build them.

Running it#

./install/install.sh --api-url https://127.0.0.1 --api-key "$(cat /path/to/key)"
journalctl -u wheelhouse-agent | grep "shown once"   # the generated admin password

Browse to https://127.0.0.1:8090, sign in as admin with that password, and change it — the account carries the same must-change flag as on an appliance. Then set up two-factor and issue an API token for anything automated.

--bind-addr changes the listen address from the default 127.0.0.1:8090.

The A/B binary swap#

install.sh keeps the previous binary at /opt/wheelhouse/wheelhouse-agent.old, health-checks the new one after the restart, and restores the old one if the check fails. The health check tries HTTPS first and falls back to plain HTTP, so a healthy TLS agent is not mistaken for a broken one.

./install/install.sh install --api-url https://127.0.0.1 --api-key "$API_KEY"
./install/install.sh rollback     # back to the previous binary
./install/install.sh verify       # health check only

This is not how the product upgrades. On an appliance an agent upgrade is a .deb replacement and a full upgrade is add system image.

Verifying a build you moved by hand#

install/sign.sh builds and checks a SHA-256 manifest of an agent binary and its UI assets, and verifies a detached signature when one is present:

./install/sign.sh manifest agent/wheelhouse-agent ui/dist/   # writes wheelhouse.manifest
./install/sign.sh verify   wheelhouse.manifest               # checksums, then signature

For release artefacts, verify against the published SHA256SUMS instead — Download and verify.

The agent package is a build input#

wheelhouse-agent_<v>_<arch>.deb on the release host is not a second way to get a router: the ISO build drops it into the image. Installing it on a stock VyOS box is a development path and is not covered by any test.

The package installs the agent, the UI it serves, the systemd unit that binds 0.0.0.0:8443 with a self-signed certificate, a first-boot unit that mints the agent's own VyOS API key and pins the router's HTTPS API to loopback, and a console-banner timer. Both units are enabled by symlink so the package works in a live-build chroot where systemctl cannot run.

See also#

• Getting started — the supported path.
• First sign-in — the appliance's port, banner and password gate.
• Download and verify — what is in a release directory, including the .deb and the bare binary tarball.
• Agent flags — every flag, including --addr and --api-key-file.
• Environment variables — what the agent reads from the environment.
• Upgrading the agent — the .deb path on an appliance, and the A/B swap here.
• The development environment — if you are building it rather than running it.
• The package — what build-deb.py produces.

Checked against install/install.sh, install/sign.sh, install/wheelhouse-agent.service, docs/deploy.md, docs/install.md, packaging/README.md, packaging/build-deb.py.