Maintain and recover a Hermes setup

A maintenance plan should explain what to do when an update succeeds, when it partly succeeds, and when the agent cannot start. For Hermes, that begins with knowing which installation owns the running application and which directory contains the workflow's data.

This guide is for the person responsible for an existing setup. It provides a runbook structure, based on official documentation reviewed on October 10, 2026. Before using any command, confirm that it applies to your installed release and distribution.

1. Record the running installation

Keep the installed version, distribution type, operating-system account, active profiles, and data location together. Record every interface or service that can start the same workflow. Include a desktop application, gateway, dashboard, or custom supervisor if present.

The current update guide assigns different owners: managed source installations use hermes update; desktop bundles use their package's updater; Docker updates replace the image while retaining the intended data mount. Store, Nix, and Termux installations have their own package-owned routes. Do not use a source-update procedure inside an immutable application package. Update ownership.

Application and dependency maintenance are also separate. Hermes PM manages tools and Python environments, so a PM operation should not be assumed to install a new Hermes application release. Package management.

2. Check what actually shipped

Read the release notes for the distribution you operate. As a concrete example, v0.21.6, released October 8, 2026, did not advance the Desktop, Termux, or Microsoft Store packages. Those remained on existing builds pending the next bundled release. v0.21.6 release notes.

Record the target version separately from the newest release you saw online. Note changes affecting providers, plugins, stored data, or the operating system. A successful update check that offers nothing is different from a failed check that cannot reach its source.

Choose a maintenance window based on the workflow's consequences. Tell its operator what work may be interrupted and how to handle inputs during the window. Keep the last accepted sample task ready for a post-update test.

3. Make a backup that matches the recovery goal

The documented hermes backup archive covers application data, including credentials, but excludes application code, downloaded runtimes, caches, and browser profiles. A profile export excludes credentials and is not equivalent to a full migration backup. An archive can contain omissions if files failed to copy, so inspect the reported exclusions and skipped files. Backup and profile-export guidance.

Treat the full archive as sensitive. Store it in an access-controlled backup location, separate from the machine if loss of that machine is in scope. Do not upload it to a public issue or send it as an ordinary troubleshooting attachment. Record when it was created and who can authorize restoration.

Check recoverability before relying on the backup. Confirm that the archive is readable, that expected profiles are present, and that the chosen restore procedure matches your distribution. Any rehearsal should keep restored messaging and scheduled work from competing with the original installation.

4. Update and inspect the result

For a managed source installation, the current guide documents a preview through hermes update --plan and an optional full pre-update backup through hermes update --backup. Default quick snapshots are limited, and a snapshot failure can warn while the update continues. Afterward, check version, diagnostics, gateway state where relevant, and the update receipt. Source update procedure.

Read warnings before calling the update complete. A functioning chat window may coexist with an optional feature that failed to rebuild or a connection that needs attention. Classify each warning against your workflow, name the owner, and keep the workflow paused if a required component is uncertain.

Repeat the original acceptance pack. Confirm ordinary input, missing information, and one permission-boundary case. Inspect both the output and the actions taken. Keep the before-and-after configuration record so a later regression has useful context.

5. Choose the right recovery problem

Separate four situations: broken application code, unavailable dependencies, damaged application data, and unwanted edits to a work project. Restoring the wrong layer can add damage or hide the evidence needed to diagnose the original fault.

Hermes project checkpoints support selected file recovery, but current documentation makes them opt-in. Their existence should be verified rather than assumed. Project rollback is not a blanket undo for sent messages, remote changes, or every installation problem. Checkpoints and rollback.

For session-storage errors, follow the dedicated recovery procedure. The official guide warns against deleting SQLite sidecar files or copying only the main database while it is active. Stop the relevant processes and inspect through the documented recovery tools before attempting repairs. Session storage recovery.

Fictional example

Alder Demo Services is a fictional business with a draft-only reporting workflow. Its operator saves a protected backup and records the current source release before an update. Afterward, the basic chat works but a required plugin is unavailable. The operator leaves scheduled reporting paused, records the exact warning, and tests the supported repair route. The example illustrates a decision process and makes no claim about an observed recovery time.

6. Close the maintenance record

Finish with a checklist:

• Running distribution and version verified
• Backup reviewed for missing files and sensitive contents
• Required services restarted through their correct owners
• Acceptance pack passed with the intended model and tools
• Remaining warnings assigned or resolved
• Old installation preserved until recovery requirements are satisfied
• Normal scheduling and delivery resumed only after approval

Bring the installation record and a redacted failure report to InstallAI when discussing maintenance help. Clear ownership and a tested recovery plan are more useful than a promise that updates can never fail.