Upgrade

The unified binary updates itself from the release channel. Updates are forward-only by design, and a failed update leaves the current binary running.

Update the agent

steelframe update

The command fetches latest.json, compares semver, downloads and verifies the newer binary, and atomically replaces the running file. It only replaces when the remote version is strictly newer; an equal version with a different SHA does not replace.

A running agent also auto-updates:

1. Polls latest.json every auto_update_minutes (default 5; 0 disables).
2. Locks dispatch when a newer version is pending, so no new workers start.
3. Drains in-flight workers. The drain gate fails closed: if the worker count cannot be read, it holds and the next watchdog tick retries.
4. Applies the binary and re-execs.

The systemd unit also runs ExecStartPre=-steelframe update, so a restart picks up a new build even if the process exited instead of re-execing.

Disable updates on a pinned host with STEELFRAME_NO_UPDATE=1.

Update the GUI

Native GUI and Web are published to the same release channel: steelframe-gui-linux-x64 and the gui/ wasm bundle. A normal channel update covers them. Web is hosted on the release channel (R2) rather than served by the agent, so a browser reload picks up a new build; the GUI origin must keep Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp for WebAssembly to run.

After an upgrade

• The DB migrates forward on startup. Migrations are not automatically reversed, so a rollback may require restoring the database too.
• If you changed the session-memory embed model, run steelframe agent memory-rebuild to build packs for the new model_id. The old packs remain as orphans under the previous prefix.
• Check the Dashboard auto_update block to confirm pending and draining have cleared.

Rollback considerations

There is no built-in rollback command. Since steelframe update only moves forward, plan a rollback as an explicit operation:

1. Stop the agent.
2. Replace the binary with a known-good build from the channel (vX.Y.Z/steelframe-linux-x64) or a backup you kept.
3. Restore the database if the upgrade migrated it and the older build cannot read it.
4. Start the agent and confirm steelframe version.

Keep the previous binary or a VM snapshot before a major release. A downgrade after a schema migration without restoring the DB is not supported.

Caution

Do not edit the binary path in the unit to a second install to “roll back”: the update check still compares against the channel and will move forward again on the next poll. Set STEELFRAME_NO_UPDATE=1 for the pinned host.

Gotchas

• Auto-update locks dispatch while a version is pending; queued tasks wait for the drain to finish.
• A failed download or checksum mismatch never replaces the binary — the agent keeps running the current version.
• install.sh always installs the latest; there is no version argument. To pin, place the binary yourself and disable updates.