Upgrading

At the end of this guide your deployment runs the new release, every Hub has been checked, and you hold a backup that takes you back if you need it. Hub files rarely change between releases. What changes is the software around them: Hubzoid's own tables, the workflow engine, the web app and Settings. Each upgrades itself at the first start of the new version, so an upgrade is a short maintenance window with a backup taken just before that start.

What you needCopy Anchor Link

• The release notes for every release between the one you run and the one you install: the changelog, the releases page (opens in a new tab) and the SDK's upgrade guide (opens in a new tab). Skipping a release does not skip its steps.
• Shell access to the deployment, in the environment where Hubzoid is installed.
• A few minutes when nobody depends on scheduled work.

Upgrade a deploymentCopy Anchor Link

hubzoid schedule status ./my-hub

sudo systemctl stop hubzoid

hubzoid backup ./my-hub --out pre-upgrade.tar.gz

pip install -r requirements.txt

hubzoid doctor ./my-hub

sudo systemctl start hubzoid

What changed recentlyCopy Anchor Link

Templates moved out of the packageCopy Anchor Link

Hubzoid no longer bundles Hub templates. hubzoid init <name> writes a small starter: every folder Hubzoid reads, three house rules for Kestrel & Oak and one check. Complete agents are ready-to-use agents in their own repositories: Software Factory, Order & Invoice Desk, Customer Desk and Engineering Desk.

• Hubs you already made from a template keep working. hubzoid init copied the files into your Hub folder, and upgrading never deletes, regenerates or updates them.

Changing agent files from the browser is off by defaultCopy Anchor Link

Proposing and approving Hub changes, the agent's remember and propose_hub_change tools, and saving connectors, channels, settings, approval rules and budgets in Settings now answer that this is off. People still read everything in Settings, which says where to change each item, and the command line and your editor work as before. To turn it back on, set in_app_editing: true in hubzoid.yaml (or HUBZOID_IN_APP_EDITING=true) and restart hubzoid run. Settings then marks those controls Beta. Files that come from an image are never written.

Settings has two groupsCopy Anchor Link

Settings is now Personal (Account, Connected accounts, Sources, Memory, My schedules) and Manage (Agents, Activity, Team schedules, People, Usage, Organization).

Other changes from that releaseCopy Anchor Link

The release that turned off browser editing and regrouped Settings also brought eight more changes.

That release changed no database tables or Hub files. Installing it and restarting, with hubzoid restart <hub> or the service, is enough.

Upgrading a gatewayCopy Anchor Link

One hubzoid backup of any Hub of a deployment covers its data directory and every Hub. Stop hubzoid run before installing, and every Hub starts again on the same release.

A deployment still run by hubzoid gateway, with separate units per Hub, moves to one hubzoid run once, offline:

1. Let waiting work finish, then stop and disable the old gateway unit, every per-Hub unit and every Slack or inbound unit with sudo systemctl disable --now <unit>. Then back up each Hub and the gateway's data folder, and hubzoid backup verify the archive.

2. Install the new release.

3. In the folder that holds the Hub folders, see what would be written, then write it:

   hubzoid upgrade --dry-run --data-dir <old data folder>
   hubzoid upgrade --data-dir <old data folder>

   It writes hubzoid.yaml from the gateway's manifest, and moves settings kept only in the database (brand, chat defaults, diagnostics limits, connectors, keys typed into Settings, channels) into their files. It never overwrites a file and never prints a secret.

4. Review the written files with git diff and commit them. Remove from each Hub's .env what is now set once, such as HUBZOID_AUTH (now sign_in:), and move sign-in client settings to the .env next to hubzoid.yaml.

5. Write the one unit for the whole deployment, start it and check every Hub:

   sudo /opt/hubzoid/agents/.venv/bin/hubzoid service install --data-dir <old data folder> --user hubzoid --write
   sudo systemctl daemon-reload
   sudo systemctl enable --now hubzoid
   hubzoid status

To go back, follow going back and enable the old units again.

Upgrading a containerCopy Anchor Link

Back up, stop the container, build or pull the new image, and start again. With the Compose files:

docker compose -f docker/docker-compose.yml exec hubzoid hubzoid backup /hub --out /hub/pre-upgrade.tar.gz
docker compose -f docker/docker-compose.yml down
git checkout v<version>
HUB_PATH=$HOME/my-hub docker compose -f docker/docker-compose.yml up -d --build

To run a published image instead, set HUBZOID_IMAGE=ghcr.io/hubzoid/hubzoid:<version>. The container upgrades its tables at its first start, the same as a native install. See Docker.

How database upgrades workCopy Anchor Link

Hubzoid versions its own tables with Alembic in two stores, each with its own version table, so they never collide with each other or with the workflow engine's.

A database already upgraded by a newer Hubzoid is refused, and the bridge stops with a message naming the store. hubzoid doctor reports it as a failure on db.operational or db.hub. The fix is to install that newer version or restore a backup, which is why going back always means restoring the backup taken before the upgrade.

Going backCopy Anchor Link

Stop everything. Restore with the new version still installed, then reinstall the previous release and start:

hubzoid restore pre-upgrade.tar.gz
pip install "hubzoid==<previous version>"

Whatever the restore replaces is kept beside it as <name>.pre-restore-<time>. Add --postgres to load an archive's single PostgreSQL dump, or load several dumps with pg_restore first. Put back the matching .env files too, if you changed any for the new release. Backup and restore covers a restore that refuses a database still in use.

Deployments moving from a release that used Open WebUI follow the dedicated steps in the SDK's upgrade guide (opens in a new tab), including hubzoid migrate openwebui.

If something goes wrongCopy Anchor Link

Next stepsCopy Anchor Link