Updates & releases

bRRAIn never updates itself. There is no background updater and no timer. A brain changes version only when someone runs brrain upgrade, re-runs the installer, or presses Upgrade for a hosted brain. Every release ships with published release notes.

What a release is

A release is one tarball, brrain-handler-<version>.tar.gz, carrying the brrain binary, the Handler's Modelfile and the continuity templates. They move together. Each release is described by a manifest (latest.json for the current stable release, <version>.json for a specific one) that names the version, the artifact URL, its SHA-256 digest and the minimum version it can be upgraded from.

brrain upgrade

| Command | Use | |---|---| | brrain upgrade -check | Installed versus available, whether an update exists, and the release's minimum upgrade-from version. Same as brrain check-updates. | | brrain upgrade -dry-run | What would be downloaded and verified, what would be replaced, where the current release would be kept, and what would be left alone | | brrain upgrade | Upgrade to the current stable release | | brrain upgrade -pin <version> | Upgrade or downgrade to exactly that published version | | brrain upgrade -rollback | Restore the previous release from /opt/brrain/.previous (no download) | | brrain upgrade -no-restart | Swap the release but leave the service alone |

brrain update is a legacy alias for upgrade.

An upgrade:

1. reads the manifest from the artifact origin (or BRRAIN_MANIFEST_BASE);
2. downloads the tarball and verifies its SHA-256, refusing on a mismatch or a manifest without a digest;
3. extracts it beside the install root and validates the contents;
4. moves the current release to /opt/brrain/.previous and the new one into place;
5. leaves /opt/brrain/extensions and /opt/brrain/ollama untouched;
6. restarts the service, unless you passed -no-restart.

Same host, same URL, same vault, same extensions.

If -check shows your installed version is older than the release's minimum upgrade-from version, ask bRRAIn support for the supported path before upgrading.

A change procedure for customer-run hosts

Before the window:

1. Read the release notes for every version between installed and target.
2. Run sudo brrain upgrade -check and sudo brrain upgrade -dry-run; keep the output with the change record.
3. Confirm disk space for another copy of the release on the install root's filesystem.
4. If the notes mention new permission scopes, review custom roles: a custom role's permissions replace the tier defaults, so it does not gain new scopes automatically.

In the window:

5. Take a fresh snapshot (brrain dr snapshot, see Backup & restore). Rollback restores the release, not the vault.
6. sudo brrain upgrade, or -pin <version> if a specific version was approved.
7. Check /version, /healthz and /readyz on 127.0.0.1:7843, and read journalctl -u brrain.
8. Exercise the basics: an answer from Ask, an MCP client session, and an audit entry.

If the new release will not run, sudo brrain upgrade -rollback. Under systemd the unit restarts the brain on failure but does not roll back on its own; that decision is yours.

Pinning

brrain upgrade -pin <version> holds a host at a version, for example through an audit period. Nothing changes until someone runs another upgrade. Record why and until when.

Hosted brains

For a hosted brain, the provisioning page shows Installed and Available and an Upgrade to X button. It upgrades in place: same pod, same URL, restart in about a minute. If the new release fails three times rapidly (each within 60 seconds of the previous), the pod's supervisor rolls back to the previous release automatically. Extensions update separately with Update in the console. See Hosted pods.

Air-gapped hosts

Mirror the manifests and tarballs inside your network and set BRRAIN_MANIFEST_BASE for both the installer and brrain upgrade. See Air-gapped install.