Skip to main content
Migration Notice
We're migrating documentation from the old portal into this one. Some things may look a little different or out of place in the meantime — we know, and we're working to get it right. If something's unclear or doesn't look right, let us know.

Vault Agents

Overview​

The Vault Agents section manages the fleet of vault agent processes running inside your vault network. Each vault agent runs autonomously on a dedicated vault host: it connects to the console over HTTPS, discovers its assigned protection groups, drives the incremental sync schedule, and manages the airgap open/close lifecycle.

Vault agents authenticate using a vault-scoped key — a special token that can only be used for vault agent registration and sync endpoints. These keys are created here in the Install tab and cannot be used to access the general console API or trigger copy-engine jobs.

Sub-tabs​

  • Dashboard — live status cards for every registered vault agent, with revoke/upgrade/remove actions and per-agent heartbeat interval editor
  • Install — Console DNS name, vault-key generation, one-liner install command, host requirements, and the hosted Vault Agent JAR upload (plus the Quantum Trust Signed .qtspkg uploader)
  • Logs — log level, upload interval, retention controls; archives are decrypted on the console and stored under /data/logs/agents/{agentId}/
info

Quantum Trust Protocol Audit Log is now a top-level Vault Operations tab — open it from the main tab bar to see every encrypted exchange across the fleet.

Version Management and Self-Upgrade​

Version Mismatch Detection​

Each vault agent heartbeat reports the agent's current version. If the console has a newer vault agent JAR uploaded (via the Install tab), the agent card shows an amber Version Mismatch badge and alarm VA-004 fires.

The mismatch badge and alarm clear automatically the next time the agent heartbeats with a version that matches the hosted JAR — either after a successful upgrade or after the hosted JAR version is changed.

Triggering Self-Upgrade​

When the Version Mismatch badge is visible and the agent's upgrade state is Idle, an upgrade button (↑ arrow) appears in the agent card action row.

  1. Click the upgrade button (↑ arrow) on the agent card. An inline amber confirmation bar appears inside the card.
  2. Click Upgrade in the confirmation bar to proceed, or Cancel to dismiss.
  3. The console marks the agent as Upgrade Pending. On the agent's next heartbeat, it receives upgradeAvailable: true.
  4. The following cycle: the agent sends status UPGRADING to the console, then fetches the upgrade manifest via the encrypted Quantum Trust Protocol (QTP) channel. The manifest contains the SHA-256 hash of the JAR and a single-use 5-minute download token.
  5. The agent downloads the JAR binary using the token, verifies the SHA-256 hash, and writes the new JAR atomically. If the hash does not match, the upgrade is aborted and the old JAR is unchanged.
  6. The agent process exits. The process manager (systemd, supervisor) restarts it with the new JAR. The vault is not closed for the upgrade and running protection group syncs are not stopped: their copy jobs keep running during the restart (unwatched by the vault agent).
  7. After restart, the agent heartbeats with the new version and picks up any copy jobs that are still running (keeping the vault open until they finish). The Version Mismatch badge clears and VA-004 auto-clears.

Upgrade States​

Badge / StateMeaning
(no badge)Versions match — no action needed
Version Mismatch (amber)Agent version differs from hosted JAR. Click upgrade button to start.
Upgrading… (blue spinner)Agent has acknowledged the upgrade and is downloading/installing.
Upgrade PendingOperator triggered upgrade; waiting for agent's next heartbeat.
Upgrade FailedDownload, SHA-256 verification, or write failed. Alarm VA-002 fires. Check agent logs.

Alarm VA-004 — Version Mismatch​

VA-004 fires the first time a heartbeat reveals a version mismatch. It is WARNING severity with a 1440-minute (24h) cooldown so it does not spam on every heartbeat. It auto-clears when versions match again — no manual clear needed after a successful upgrade.