Updates
How B3IQ keeps the host agent current on the machines it hosts and ships: signed, automatic self-updates, a per-machine hold, and automatic rollback.
B3IQ ships signed self-update for the host agent on the machines it hosts and manages. Updates are verified before they can run and apply automatically by default. B3IQ keeps your fleet current without anyone babysitting it, and a node never silently swaps to an unverified binary. This page describes the update lifecycle and what you can see and control per machine.
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 apply and rollback smoke evidence) is still a launch gate. Treat current provisioning 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 architecture.
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; b3iq machines get <machine> --json carries the
same update_status block.
Apply automatically
Auto-update is on by default, per machine: once a candidate is staged and waiting, the control plane rolls it out — at most five machines per cron tick, so each release stages itself across the fleet — without anyone clicking anything. A machine that already applied is left alone for about a day afterwards, so a build that fails and rolls back cannot re-apply in a loop. 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 exactly 1 to disable the periodic self-update check. The agent will not download or stage candidates. Any other value leaves checks on. |
| B3IQ_SELF_UPDATE_INTERVAL | 1h | How often the agent checks for a newer build. Accepts a Go duration such as 6h; an unparseable or non-positive value falls back to 1h. |
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.
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.