Update and roll back

hal0 updates itself. The hal0 update CLI is a thin client over the daemon’s /api/updates/* surface, so the same code path runs whether you trigger an update from the shell or the dashboard. The actual swap is a cosign-verified, atomic symlink swap of /usr/lib/hal0/current — your config (/etc/hal0) and state (/var/lib/hal0) are untouched by the swap itself.

Read this before your first v1.0 update

If you’ve hand-edited custom entries into /etc/hal0/profiles.toml, the first hal0 update that crosses the v1.0 schema boundary wipes and reseeds that file. Skip to The profiles.toml reseed before you run it.

Check for an update

hal0 update --check

Fetches the release manifest for your channel and diffs it against the running version. It shows current → latest (channel) plus whether an update is available, and (when present) the release date, notes URL, digest, and signer identity. A revoked (yanked) release is never reported as available even if it’s newer.

Apply an update

hal0 update

Checks, then stages the update, shows you the release notes (highlights, breaking changes, migrations — pulled from the release manifest), asks for confirmation, and applies. Skip the confirmation prompt for scripted runs:

hal0 update --yes

The CLI polls the apply job until it reaches applied or failed. After a successful apply the daemon try-restarts hal0-api itself — the CLI never touches systemd.

To pin a specific version instead of the latest:

hal0 update --target v1.0.0

Stuck on 1.0.0-rc.1? Use --target

A box still running 1.0.0-rc.1 can’t see later releases as available: its CLI predates the prerelease-aware version comparison that shipped in rc.2 (#1663), so the old fallback ranks 1.0.0rc1 above plain 1.0.0 and both hal0 update --check and a plain hal0 update report nothing to do. This only affects boxes that go straight from rc.1 to a later release — updating rc.1 → rc.2 first works normally.

--target bypasses the availability check entirely and pulls the requested release directly:

hal0 update --target 1.0.0

Note

hal0 update refuses outright on an editable/dev install (pip install -e), with an actionable message to install from a release wheel instead.

Channels

Three release channels are available: stable, preview, and nightly. Set your channel (it persists in hal0.toml), which also runs a check:

hal0 update --channel preview

Settings → Updates: current version, available release, and channel selector.

How the atomic update works

1. Fetch the release manifest for the channel.

2. Download the release tarball plus its detached cosign signature into a per-version cache under /var/lib/hal0.

3. Verify the SHA-256 digest against the manifest, then the signature with cosign verify-blob against the exact GitHub Actions OIDC identity declared in the manifest. A missing cosign binary or a failed verification aborts the update — nothing is swapped.

4. Extract the tarball and run any forward config migrations the release needs — including, on a pre-v1.0 box, the one-time profiles.toml reseed described below.

5. Swap the /usr/lib/hal0/current symlink atomically, then reinstall the code into the venv. A failed re-install rolls the symlink back so current and the venv never diverge.

6. Re-render every slot’s systemd unit through the newly installed code. This step never bounces a running slot — the CLI shows a “N slots need restart” banner post-apply; pass --restart-slots to bounce only the slots left running the pre-update launch command.

7. Record the prior symlink target in /var/lib/hal0/hal0.previous for rollback.

The profiles.toml reseed (a pre-v1.0 one-time wipe)

hal0’s seed profile catalogue is baked into code, not into /etc/hal0/profiles.toml — the file only ever holds your own custom entries. Older (pre-v1.0) installs could accumulate stale materialized seed rows in that file alongside your custom ones. As part of crossing the v1.0 schema boundary (any config still at schema_version < 2), hal0 update runs a one-time reset: it deletes profiles.toml outright, so the next config load serves the catalogue purely from code.

This is a real, destructive delete — not a merge — and it takes your custom profiles with it.

1. Automatic backup, every time. Before the file is touched, hal0 copies it to /var/lib/hal0/backups/profiles-<UTC-timestamp>.toml (e.g. profiles-20260731T120000Z.toml). This backup is unconditional — it happens whether or not you have custom profiles.

2. Consent, if you have custom profiles. If the file contains only materialized seed rows, the reset proceeds silently. If it contains profiles that aren’t part of the built-in catalogue, hal0 update stops and lists the exact custom profile names at risk, asking you to confirm before it deletes them.

3. Headless runs default to skip, never wipe. Running non-interactively without --yes skips the reset entirely rather than deleting anything without a human present to confirm.

4. No restore command. There is no hal0 profile restore or similar — recovering a wiped custom profile means manually copying the relevant [[profile]] block back out of the timestamped backup file into /etc/hal0/profiles.toml yourself.

Caution

Rollback does not undo this. hal0 update --rollback (below) only swaps the installed code tree back — it never touches profiles.toml. If the reset already ran and deleted your custom profiles, rolling back your hal0 version does not bring them back; you still have to restore from the timestamped backup by hand.

Preserve your custom profiles before updating

Belt-and-suspenders beyond the automatic backup — do this before your first update past the v1.0 boundary if you have any hand-written entries in profiles.toml:

sudo cp /etc/hal0/profiles.toml ~/profiles.toml.bak

Note the names and settings of anything custom in there. After the update, if the reset ran, restore what you need by hand — either from your own copy, or from /var/lib/hal0/backups/profiles-<timestamp>.toml, which hal0 wrote for you automatically:

sudo cat /var/lib/hal0/backups/profiles-*.toml

Then re-add the custom [[profile]] blocks you want back into /etc/hal0/profiles.toml with hal0 config edit profiles (or hand-edit and hal0 config validate before reloading).

Note

This reset only ever fires once, on a box crossing the schema_version < 2 boundary. Once your config is at v1.0’s schema, later updates don’t re-run it — this whole section is a one-time migration concern, not an ongoing behavior of hal0 update.

Roll back

If an update misbehaves, revert to the previously installed tree:

hal0 update --rollback

Rollback reads /var/lib/hal0/hal0.previous, atomically swaps the current symlink back to it, then reinstalls that prior tree into the venv and re-renders every slot unit. Unlike an apply, a rollback does not try-restart hal0-api for you — the running process keeps serving the newer code until you restart it yourself. It warns (without erroring) if the previous tree is gone on disk, or if the current config’s schema version is ahead of what the previous tree understands — migrations are forward-only, so the older tree just parses what it can. If no previous-version record exists, there’s nothing to roll back to.

As covered above, rollback never restores profiles.toml — that’s a config-state change, not a code-tree change, and the two are deliberately decoupled.

Repin the OpenWebUI companion container

hal0 update owui --check
hal0 update owui --target <digest>
hal0 update owui --yes --force

Independent of the main hal0 update flow — repins the bundled OpenWebUI container by SHA-256 digest.

See also

• Edit configuration — /etc/hal0 is preserved across updates, with the one exception above.
• Logs and activity — watch the apply job and hal0-api restart.