Updates
How the B3IQ host agent and desktop companion stay current with signed, automatic self-updates, a per-machine opt-out, and automatic rollback.
B3IQ ships signed self-update for the host agent and a separately signed updater for the desktop companion. Updates are verified before they can run, and apply automatically by default — every machine has its own opt-out — so a fleet stays current without operator babysitting and a node never silently swaps to an unverified binary.
Signed self-update is shipped: candidates are signature- and checksum-verified before they can apply. Full production trust hardening — release-manifest signature enforcement with the production public key, plus cross-platform apply and rollback smoke evidence — is still a launch gate. Treat current installers and update paths as a pilot. See Release trust for the remaining gates.
Host Agent Update Lifecycle
The host agent checks for an update about once an hour, and on its own it only ever stages a verified candidate — the agent never swaps in a new binary by itself. Applying is a control-plane decision: by default the fleet auto-applies staged candidates for you, a few machines at a time; turn a machine's auto-update toggle off to apply on your own schedule instead.
Check
On its interval (about hourly) the agent asks the public release route whether a newer host-agent build is available for its platform.
Download
If a newer build exists, the agent downloads the candidate to a staging location alongside the running binary. The running service is not touched.
Verify
The candidate is checked against its Ed25519 signature and checksum. A candidate that fails either check is discarded and never staged for apply.
Stage
A verified candidate is staged and surfaced as available. The machine's Diagnostics tab in the account dashboard shows the running version and the staged one side by side, and the CLI reports the pending version.
Apply automatically
Auto-update is on by default, per machine: once a candidate is staged and waiting, the control plane rolls it out — a handful of machines at a time — without anyone clicking anything. Turn a machine's auto-update toggle off to keep staging candidates without applying them, then apply on your own schedule with the dashboard's Update now action.
Health-check and roll back
After restart the agent health-checks the new version. If the new build fails its health check, the agent automatically rolls back to the previous working binary and keeps the node serving.
Auto-update is a per-machine toggle on its Diagnostics tab in the account dashboard (default on). The dashboard is auth-gated; reach it from your operator session rather than a public URL.
CLI
You can inspect and plan host-agent updates from the command line.
bashb3iq-host update-service --dry-run
Plans the update — resolves the candidate and reports what would change — without applying anything.
bashb3iq-host version
Reports the running host-agent version. A staged update candidate appears in the dashboard.
Tuning The Updater
The host-agent self-updater — checking, downloading, verifying, and staging — is controlled with environment variables on the node itself. This is a different lever from the account-dashboard auto-update toggle above: the variables below decide whether the agent looks for updates at all; the toggle decides whether a verified, staged candidate gets applied automatically once it's ready. Defaults keep update checks on.
| Environment variable | Default | Effect |
|---|---|---|
| B3IQ_SELF_UPDATE_DISABLED | unset | Set to 1 to disable the periodic self-update check entirely. The agent will not download or stage candidates. |
| B3IQ_SELF_UPDATE_INTERVAL | 1h | How often the agent checks for a newer build. Accepts a duration; lengthen it to check less often. |
Do not set B3IQ_SELF_UPDATE_DISABLED on a node that serves routed
work or sits on an untrusted network. Disabling self-update means a node misses
security and protocol-compatibility fixes and can drift out of route
eligibility. Disable it only for an air-gapped or pinned-version maintenance
window, and re-enable it afterward.
Desktop Companion
The desktop companion updates through its own signed updater using minisign signatures, separate from the host-agent self-update path. It verifies the signature on each update before applying. See Desktop app for install and update behavior, and Release trust for the platform-by-platform signing and smoke gates that still apply.
Common Blockers
No verified candidate is staged. Either the node is on the latest build, the
check has not run yet (it runs about hourly), or self-update is disabled via
B3IQ_SELF_UPDATE_DISABLED. Run b3iq-host version to
confirm the running version; both the current and latest version show on the
machine's Diagnostics tab in the dashboard.
The candidate failed signature or checksum verification and was discarded. The agent will retry on its next interval. Confirm the node can reach the public release route over outbound HTTPS.
Applying an update restarts the service, whether the fleet's default rollout
triggered it or you applied it manually. If the new build fails its health
check, the agent rolls back to the previous working binary automatically, so
the node returns to its prior version. Re-run b3iq-host version
to see which version is running.
Turn off that machine's auto-update toggle on its Diagnostics tab in the
account dashboard. The agent keeps checking, verifying, and staging
candidates as usual — it just won't apply one until you trigger it with the
dashboard's Update now action. To check less often,
lengthen B3IQ_SELF_UPDATE_INTERVAL.