Upgrade the agent only#

You will end up running a new wheelhouse-agent and web UI on the same image, without a reboot. This is how a fix to the control plane reaches a router between image releases.

It is not the ordinary upgrade path. When a release changes both the image and the agent — which is every release, because the image contains the agent — install the image and reboot. That is one operation and it is the whole upgrade. Reach for the .deb only when you specifically want the control plane moved without a reboot.

Before you start#

• A backup.
• Shell access to the router — the console, or SSH.

• The version you are going to, and the version you are on:

  bash

  wheelhouse-agent --version
  dpkg-query -W -f='${Version}\n' wheelhouse-agent

Step 1 — Fetch and verify#

curl -fLO https://releases.rhymelikedi.me/latest/wheelhouse-agent_0.5.1_amd64.deb
curl -fL  https://releases.rhymelikedi.me/latest/SHA256SUMS | sha256sum -c --ignore-missing

A checksum proves the file survived the network. It does not prove who built it — the checksum comes from the same host as the package. See Learn that a release exists for where signing stands.

Step 2 — Install it#

sudo dpkg -i wheelhouse-agent_0.5.1_amd64.deb

The package's postinst reloads systemd, starts the console-banner timer and restarts wheelhouse-agent, so the new binary is running when dpkg returns. Nothing under /config is touched, so accounts, the audit log and the licence carry over untouched.

Downgrading works the same way with an older .deb.

There is no apt repository; the packages are files on the download host.

Step 3 — Confirm#

systemctl status wheelhouse-agent
curl -sk https://127.0.0.1:8443/health
wheelhouse-agent --version

Then reload the web UI. Your browser may hold cached assets from the previous version; a page that looks broken right after an upgrade usually wants one hard reload.

Two caveats, both real#

1. It is not covered by a test. Nothing in CI installs the package on a VyOS system. The package's dependencies — bash, python3, dialog, curl — are all present in the shipped image, so the install will resolve; whether every file lands where it should on an installed system is not something this project has verified.

2. It writes into /usr, which belongs to the image. An image upgrade installs a fresh /usr from the new ISO, so an agent installed this way is replaced by whatever version that ISO carries. That is usually what you want — but if you .deb-upgrade to a newer agent and then image-upgrade to an older ISO, you go backwards. Keep the two in step.

The off-router agent#

install/install.sh installs the agent on a machine that is not the router and points it at an existing VyOS box's HTTP API. It has its own A/B upgrade: it backs up the old binary, health-checks the new one and rolls back on failure.

./install/install.sh                # install, or A/B upgrade if already installed
./install/install.sh verify         # health-check the running agent
./install/install.sh rollback       # back to the previous binary

That path uses /opt/wheelhouse, /etc/wheelhouse and port 8090, none of which exist on a Wheelhouse router. It is a development and lab arrangement, not the product — see The developer install.

Undoing it#

Install the older .deb:

sudo dpkg -i wheelhouse-agent_0.5.0_amd64.deb
systemctl status wheelhouse-agent

Or, if the agent will not start at all, boot the previous image from GRUB — the agent in that image is untouched by anything dpkg did to this one.

See also#

• Upgrade the whole system — the supported path
• Learn that a release exists
• Locked out of the UI — if the new agent will not start
• Agent settings — where the start-up flags in force are shown

Checked against docs/upgrade.md · packaging/README.md · install/install.sh · agent/main.go