HostAgentics Docs

HostAgentics Updates

Last updated: 2026-08-06

This document describes how runtime software is updated on the HostAgentics platform: the version catalog, update channels, the update flow, and rollback rules. The governing principle: **untested versions are never deployed to customer runtimes.** Update rules are encoded in `packages/updates`.

1. Version catalog

Every runtime image version is recorded in the version catalog (`runtime_versions`) with the fields that make deployment decisions safe:

| Field | Meaning |

| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |

| `version` | Version string, unique per runtime kind |

| `imageDigest` | Digest-pinned image reference — floating tags are forbidden in production |

| `tested` | Whether the version passed the platform's test pass (must be `true` before any deployment) |

| `securityStatus` | `ok` / `advisory` / `critical` — drives channel promotion |

| `migrationRequired` | Whether the version changes storage or data formats |

| `rollbackCompatible` | Whether reverting to the previous version is safe after this one |

| `releaseNotesUrl`, `sourceCommit`, `releasedAt` | Traceability |

The catalog's tested defaults per kind (digest-pinned in code): n8n `2.33.4`, OpenClaw `2026.7.1-2`, Hermes Agent `v2026.8.3` — see `docs/runtime-adapters.md`. New versions enter the catalog only after testing; a version with `tested=false` is **not deployable**, period.

2. Update channels

Each runtime has an update channel (`runtimes.updateChannel`):

  • **`stable` (default)** — tested versions with security status `ok`. Routine updates land here.
  • **`security_only`** — only versions that fix a `critical` (or `advisory`, when critical is unavailable) security issue. For customers who want minimal churn.
  • **`manual`** — no automatic updates; the customer (or support, with consent) triggers updates explicitly. Security-critical updates are still _recommended_ on this channel but not forced.

    • A `critical` security status can prompt expedited promotion across channels; the catalog record and the change are audited.

    3. Update flow

    Every update runs the same sequence, executed by the worker as a `runtime_operations` entry (type `update`) with a correlation ID:

    1. **Backup** — a provider-confirmed snapshot set is taken first (see `docs/backups.md`). No completed backup, no update.

    2. **Validate** — the target version must be `tested`, match the runtime's channel policy, and pass compatibility checks (`migrationRequired`, `rollbackCompatible`).

    3. **Deploy** — the digest-pinned target image is deployed to the runtime service.

    4. **Verify (health)** — the runtime's health probe must pass after deploy (n8n `/healthz`, OpenClaw gateway, Hermes `/api/status`).

    5. **Smoke** — a runtime-appropriate smoke check confirms the service actually works (not just "process up").

    6. **Stabilize** — the runtime stays in a stabilization window (`update_operations.stabilizationUntil`); if it degrades during the window, rollback is triggered.

    The update is recorded in `update_operations` (from/to version, linked backup, status) and audit-logged.

    4. Rollback rules

  • **Automatic rollback is recommended and enabled by default** when health, smoke, or migration fails during the window. The engine restores the pre-update backup and redeploys the previous version.
  • Rollback is only performed to a **known-good previous version** (tested, digest-pinned, `rollbackCompatible` from the new version's perspective).
  • If `rollbackCompatible=false`, the engine does **not** auto-rollback blindly: it preserves the pre-update backup and alerts on-call for a manual decision, because reverting could itself corrupt data (e.g. a forward-only data migration). The pre-update backup is always retained for the full retention window.
  • A rollback is recorded as `rolled_back` and audited with the correlation ID of the original update.

    • 5. Untested is never deployed

    The deployment path refuses any version with `tested=false`, regardless of channel, urgency, or manual override. The only way a version becomes deployable is catalog testing. This invariant is enforced in `packages/updates` and the worker; the version catalog is the single source of truth for what may run on customer runtimes.

    6. Related documents

  • `docs/runtime-adapters.md` — how adapters consume the catalog
  • `docs/backups.md` — the pre-update backup requirement
  • `docs/monitoring.md` — health verification during updates
  • `docs/database.md` — runtime_versions / update_operations schema