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 described here so that material naming port 8090 is not mistaken for the appliance.

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 a host has to already have#

These are facts about the router you point at, not steps to take. They are satisfied by installing the image; a host that does not already run VyOS has no API to talk to and no key to read, so this section is a description of the prerequisite rather than a way to satisfy it.

• 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 is not a second way to get a router, and it is not distributed (decided 2026-09-10): the ISO build drops it into the image, and that is where it goes. Installing a package you built yourself 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.
• Agent flags — every flag, including --addr and --api-key-file.
• Environment variables — what the agent reads from the environment.
• Upgrading the agent — why there is no separate agent upgrade 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.