System updates
Install a signed appliance release from your update channel or from an offline bundle, watch it apply, roll it back, and read what the host agent last repaired.
- Version: 0.4
- Role: admin_user
- Type: task
System Updates installs signed appliance releases. The page describes itself accurately: Install signed appliance updates and roll back if needed. Updates are verified and applied by the host updater. The gateway you are talking to never installs anything — it records your intent, and a privileged daemon on the host does the work, because replacing the gateway's own container would otherwise kill the process performing the update.
What do I need?
- Licence
- Any
- Role
admin_user
Prerequisites
- The appliance has completed the first-boot setup wizard.
- The updater daemon is running on the appliance host. The dashboard queues work; nothing executes without it.
- For an online install: an update channel configured on the appliance, and the update host pinned in SYSTEM_UPDATE_ALLOWED_HOSTS. An empty allowlist refuses every online install.
- For an offline install: the .cidupd bundle for your release, downloaded on a machine that can reach the customer portal.
- A recent backup, or the confidence that the automatic rollback is enough. Migrations run before the new images start.
/assets/screenshots/system-update@0.4.pngWhat the tiles tell you
| Tile | What it holds |
|---|---|
| Installed version | The running release, and whether a previous one is available to roll back to. |
| Update available | The version the channel offers, or up to date. |
| Channel | The channel the installed release came from, and the host it is fetched from. Only stable exists today. |
| Last update | The most recent run in this session, as from → to with its outcome. |
The check is done by your browser, not by the appliance: the page reads the configured channel URL and fetches the manifest itself. On an air-gapped box that fetch fails silently and the page shows the offline instructions instead. Nothing phones home on a timer — the online install runs only when you press the button, and the page says so.
Install from the update channel
Open the update page
Select System Updates.
If a newer release is offered, a banner reads Update available: version with the minimum version it can be applied from, the channel and signed release.
Read what you are about to install
Read the estimate under the banner.
It gives a range in minutes, how many migrations are pending and the size of the database it measured them against, and states whether writes are expected to block. The estimate is computed once and does not drift while the update runs.
Start the install
Select Check & install, or the button on the banner. That button reads Install version where the appliance has a channel configured and Fetch & install version where you supplied the manifest URL yourself.
The daemon verifies the manifest signature against the appliance's trust anchors before anything is staged. An unsigned or wrongly signed release never reaches the disk.
Watch it apply
Watch the Update in progress tile.
It streams the phase and message live: verification, staging, backup, migrations, swapping in the new services, health, then smoke tests. The stream survives the gateway restarting itself mid-update and reconnects for up to about five minutes.
Confirm the result
Wait for the terminal phase.
A success ends on done and a toast reports Updated to version. Installed version now names the new release and Last update shows the transition.
Install from an offline bundle
The page carries its own three-step summary for this, under No internet? Updating an air-gapped appliance.
Note the installed version
Read Installed version.
The bundle you need must be applicable from it — a release can declare a minimum version to upgrade from.
Download the bundle elsewhere
On a connected machine, download the .cidupd file for the release from the customer portal.
Only that extension is accepted.
Upload it
On the Upload bundle tab, select Choose bundle (.cidupd) and pick the file.
The upload is chunked and resumable, and a progress percentage is shown. Large bundles do not need one unbroken request.
Verify before you commit
Read the release preview that appears.
It names the release, its channel, the minimum version it applies from, how many services it replaces and how many migrations it carries. Verification happens before you commit to installing.
Install
Select Install version.
The same phases run as for an online install.
Roll back
Danger
A rollback restores the previous release's images and its database snapshot. Data written since the last update may be lost. The confirmation dialog says exactly that.
Confirm a previous release exists
Read Installed version. Its sub-line reads rollback available, and the header button names the version.
Without a recorded previous release the button is disabled, and the daemon would refuse with no previous release recorded to roll back to.
Roll back
Select Roll back to version, then confirm.
The daemon snapshots the current database first, restores the previous release and its snapshot, and starts it. A toast reports Rolled back to version.
A failed install rolls back on its own, without being asked, and reports Update failed — rolled back to the previous version. An interrupted update is detected on the next start and recovered the same way.
Read the host repair status
Some repairs a signed release cannot make to itself: the updater's own code, the host unit that watches for intents, the deployment profile, and keys missing from the appliance's environment file. A host agent does those, and this page reports what it last did.
The Host repair tile names the agent release and the box release it ran against, then lists each host migration with its state — applied, pending, failed or skipped — and any warnings from its inventory. The tile is hidden on a deployment where the agent has never run.
Note
There is no button here. The agent runs on its own cadence: shortly after start, again when the box's release changes, every 30 minutes otherwise, and every minute while something is pending. It waits for the updater to be idle before touching anything.
Change the deployment mode
When the appliance records a deployment mode, the page offers it here.
| Option | The page's description |
|---|---|
| AI Gateway | Chat + API proxy to LLM providers with guardrails. |
| Inline inspection (SWG/ICAP) | Inspect browser/SWG traffic; starts cid-inline-proxy. |
| Both | Gateway and inline inspection together. |
Select a mode and then Apply mode. A toast reports Deployment mode set to mode — the host is recreating the stack, and the API restarts briefly. Only one host reconcile runs at a time; a second is refused with a host reconcile is already pending; wait for it to finish.
Fields reference
| Setting | Where it lives | Effect |
|---|---|---|
SYSTEM_UPDATE_CHANNEL_URL | Appliance environment | The manifest the browser fetches to learn what is available. Unset means no online check. |
SYSTEM_UPDATE_ALLOWED_HOSTS | Appliance environment | The hosts an online install may fetch from. Empty refuses every online install. |
SYSTEM_UPDATE_MAX_BYTES | Appliance environment | A size cap on relayed bundles. |
SYSTEM_UPDATE_PUBLISHER | Appliance environment | Marks this deployment as the release source. Such a box cannot install from its own registry. |
CID_VERSION | Image environment | The version shown when neither the release manifest nor the version file answers. |
CID_UPDATE_ROOT | Appliance environment | The shared state tree the gateway and the daemon exchange intents and status through. |
The version shown on the page has a precedence: the active release manifest, then the version file the updater writes on apply, then the version baked into the image, then a last-resort baseline.
Update phases you will see in the log panel: queued, trust, verifying, staging, backup,
migrating, swapping, applying, restarting, adopting, health, smoke, and one of
done, verified, failed, rollback, rolledback or recovering. The dashboard treats
done, verified, failed and rolledback as terminal.
Warning
An update writes no row to Event logs. The durable record is the daemon's own status and log files under the appliance's update state directory, plus the host agent's ledger. Collect those if your change-management process needs update evidence.
Verify
- Installed version names the release you installed, and its sub-line names the one you came from with rollback available.
- Update available reads up to date, or offers only a release newer than the one you just installed.
- The Last update tile shows from → to · ok.
- Sign out and back in, then make one chat request and open two administrative pages. All three succeed — the smoke phase checks health, but only your own traffic proves the deployment.
- The Host repair tile, if present, reports every migration as applied or skipped, with no failures.
If it fails
The page shows version 0.0.0, or the update buttons return an error:
The System Updates page shows 0.0.0, or the update buttons return 500
You might see: System Updates shows version 0.0.0 · current version 0.0.0 · update check returns 500 · install update → 500
Before you start
Checks
- 1
Read the product version the appliance reports
diagnostics · appliance.version = "0.0.0"
- 2
Verify an update channel is configured
diagnostics · appliance.channel
- 3
Verify the release channel answered on the last attempt
diagnostics · appliance.update.channelReachable = true
- 4
Check whether an update or host-repair intent is stuck waiting for the host updater
diagnostics · appliance.update.pendingIntent
- 5
Read the host-repair status, which is what the page renders alongside the version
GET /admin/system-update/host-repair
Causes and fixes
| Reached when | Cause | Explanation, fix and verification |
|---|---|---|
| check 1 fails | version-file-missing (warning) | The appliance reads its installed version from a file the image build writes. When that file is absent or unreadable the version falls back to 0.0.0, and every comparison against the channel manifest then looks like a downgrade — which is why the page can show 0.0.0 and simultaneously refuse to offer an update. Fix: Run the host repair from Settings → System Updates, which rewrites the appliance version file, then reload the page. If host repair is unavailable, the version can be restored by re-running the installer's finalisation step; see Update the appliance. Verify: diagnostics · appliance.version = "0.0.0" If that does not apply: Attach the support bundle. A 0.0.0 that survives host repair means the image was built without its version stamp. |
| check 2 fails | manifest-url-unset (warning) | No release channel is configured, so the update check has no manifest to fetch. The API rejects the call with a 400 naming the missing manifest URL, which the page surfaces as a failed button rather than as a configuration prompt. Fix: Set the update channel under Settings → System Updates. On an air-gapped appliance, choose the offline channel and upload the update bundle instead of pointing at a URL. Verify: diagnostics · appliance.channel |
| check 3 fails | channel-unreachable (warning) | The channel is configured but the manifest fetch failed — no DNS, no egress, or an outbound proxy that is required and not configured. The fetch failure surfaces as a 500 from the update endpoint. Fix: Fix outbound access to the channel host, or switch the appliance to offline updates. Read the DNS and egress probes in the diagnostics snapshot separately: resolution succeeding does not mean the HTTPS fetch succeeds, and a proxy-only network needs the proxy configured explicitly. Verify: diagnostics · appliance.update.channelReachable = true |
| check 4 fails | updater-daemon-not-running (critical) | An intent is queued but nothing is executing it. The gateway only records the intent; the privileged updater daemon on the host performs the work. When that daemon is not running, intents accumulate and every subsequent action appears to hang or fail. Fix: Start the updater daemon on the appliance host and confirm the queued intent moves out of the queued state. Do not queue further intents until it does; a backlog makes the failure harder to read. Verify: diagnostics · appliance.update.pendingIntent If that does not apply: Attach the support bundle plus the updater daemon's own log from the host. |
| check 5 fails | host-agent-absent (warning) | The host-repair endpoint cannot answer because the host agent has never written its inventory. The page then has no host-side data to render beside the version, and the combination reads as a broken page. Fix: Run the host agent's inventory job on the appliance and reload the page. This is expected on a non-appliance deployment, where there is no host agent at all and the update page is not the supported upgrade path. Verify: GET /admin/system-update/host-repair |
The page rewrites the daemon's technical failures into sentences. The ones you will meet:
- That file isn't a valid update bundle. → the upload is not a genuine signed bundle. Install from your channel, or download the bundle again.
- The update's signature couldn't be verified. Only releases signed by your vendor can be installed. → the manifest failed against every trust anchor on the box.
- That release is older than the one installed — downgrades aren't allowed.
- cannot jump from A to B: this release requires at least C. Install intermediate releases first. → apply the intermediate releases in order.
- A service didn't come up healthy during the update, so it was rolled back. → the health or smoke phase failed and the automatic rollback ran. Retry, then contact support.
- Couldn't pull the update images — the registry rejected the request. → the appliance's registry credentials. Check them, or use an offline bundle.
And from the gateway itself:
- online install requires SYSTEM_UPDATE_ALLOWED_HOSTS to pin the update host → the allowlist is empty, which is the shipped default on a plain Docker deployment. Set it to the update host. A field appliance repairs this itself through the host agent.
- update host 'host' is not in SYSTEM_UPDATE_ALLOWED_HOSTS → the manifest URL points somewhere the allowlist does not name.
- bundle filename must end with .cidupd → the wrong file.
- incomplete upload: have n of m bytes → the chunked upload did not finish. Upload again.
- offset mismatch → a resumed upload disagreed with the server about how much had arrived. Start the upload again.
- This deployment is the update source → you are on the hub that builds and signs releases. It publishes from host tooling and cannot install from its own registry.
- ROLLBACK ALSO FAILED: … Manual recovery needed. → both the install and its rollback failed. Do not queue more intents; contact support with the daemon's log for that request id.
Next steps
- Update the appliance — planning an upgrade, the release channel and the offline bundle path.
- License — an update never changes your package; the licence file defines capabilities.
- Backup and restore — what to have in hand before a major upgrade.
Last updated on