Upgrade the whole system#

You will end up with a new Wheelhouse image installed beside the running one, both on disk, and the new one booting by default. Kernel, VyOS, the agent, the web UI and the installer all move together, because they all come from the image.

This is VyOS' own add system image, and it is what makes an upgrade safe: a bad image is one reboot away from being undone, not a restore.

Before you start#

• Take a backup. Take a backup that is actually complete. Every time, without exception. It takes a minute and it is the only thing standing between a bad upgrade and a rebuild.
• The admin role.
• The URL of the new image on the download host.
• Enough free space on / for a second image. Check System → Overview.

Step 1 — Install the new image#

From the UI, as an admin: System → Overview → Boot images.

1. Put the image URL in Install an image from a URL and press Install. Use the direct link to the ISO on the download host, for example https://releases.rhymelikedi.me/v0.6.0/wheelhouse-0.6.0-amd64.iso.
2. The router downloads and installs it. This takes minutes — the request stays open until the router is done and the UI shows Installing… the whole time. Do not close the tab.
3. The new image becomes the default boot image. The running image does not change until you reboot.

From the API:

R=https://<router>:8443
T=wh_...                                    # an admin token
curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"op":"add","url":"https://releases.rhymelikedi.me/v0.6.0/wheelhouse-0.6.0-amd64.iso"}' \
  "$R/api/system/image"

op may be add, show, set_default or delete. The endpoint is admin-only and audited — the audit log records image-add with the URL.

Air-gapped routers cannot be upgraded through the product. add requires an http(s) URL; there is no way to hand it a file already on the router and no upload endpoint. On such a box, use VyOS' own command at the console, which does accept a local path:

add system image /path/to/wheelhouse-0.6.0-amd64.iso

Step 2 — Reboot#

From System → Overview, typing the host name to confirm. Or:

curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"action":"reboot"}' "$R/api/system/power"

Or reboot at the console.

Step 3 — Check what came across#

/config is VyOS' persistent partition and add system image carries it into the new image. That should cover:

Check all five, because this is the run nobody has recorded:

# 1. The new image is running, and the old one is still there
show system image

# 2. The configuration survived
show configuration commands | wc -l

# 3. The agent is up and can reach the router
curl -sk https://127.0.0.1:8443/health
wheelhouse-agent --version

Then in the browser: sign in with your existing account, look at the audit log for your history, and check the Licence page still shows a valid licence.

Your browser may hold cached UI assets from the previous version. A page that looks broken immediately after an upgrade usually wants one hard reload.

Undoing it#

The old image is still on disk, which is the whole point.

• From the UI, if it is reachable: System → Overview → Boot images → Boot by default on the old image, then reboot.

• From the console:

  bash

  set system image default-boot          # interactive picker
  reboot

• From the boot menu: GRUB lists both images. Pick the old one for a single boot. This is the path that works when the new image will not bring the network or the agent up at all.

Delete the old image only when you are done with it — from Boot images (Delete, offered on any image that is not running) or delete system image.

Upgrading more than one router#

There is no fleet-wide upgrade. The Fleet page reads version and configuration from each router and can push configuration to one; it has no image action. Do each router through its own UI or its own POST /api/system/image, and do one first and live with it for a while before doing the rest.

Reinstalling from a newer ISO is not an upgrade#

wheelhouse-install refuses to run on an installed system and tells you to use add system image instead. Booting the new ISO and installing over the disk erases everything including /config, and gives you a new machine. If you need to rebuild a box, that is a restore, not an upgrade.

See also#

• Upgrade the agent only
• Learn that a release exists
• Take a backup that is actually complete
• Boot images
• Download and verify

Checked against docs/upgrade.md · agent/parity.go · docs/hardware.md · ui/src/pages/SystemActions.tsx