Installation, update, and recovery
Hermes treats code, user data, and running services as separate lifecycles. Installers create a usable source install and publish its command. hermes update changes only installs that own their code, protects user state, then moves every affected service to the new code. Diagnostics and restore paths keep a failed install recoverable without guessing which process or package manager owns it.
Installation ownership
Installation ownership identifies the actor that may replace the Hermes code. A source checkout owns its own updates. A sealed tree belongs to the tool that installed it, so the CLI refuses an in-place update and gives that tool as the next step.
The install scripts provide the same staged contract on POSIX and Windows. They acquire the source tree and bootstrap tools, let the package manager create the runtime, prepare user data, publish the command, and optionally configure the gateway or desktop product. Heavy tools and optional features remain package-manager choices rather than installer-owned files.
| Install shape | Code owner | Update path |
|---|---|---|
| Git source checkout | Hermes CLI | hermes update |
| Desktop app bundle | Desktop app | Desktop app update controls |
| Docker image | Image or deployment tool | Pull and replace the image |
| Nix store path | Nix | Flake or profile rebuild |
| Termux package | APT package manager | pkg upgrade hermes-agent |
| Commit build or other external tree | Builder or external steward | Obtain a new build from that steward |
The install identity and the update stamp make this decision durable across profiles and command launches. This prevents a development checkout from updating a desktop or packaged install that happens to share the same Hermes home.
References: hermes_cli/steward.py• L7-17 hermes_cli/steward.py• L210-236 hermes_cli/update_contract.py• L82-146 hermes_cli/install_identity.py• L61-107
Installation stages
The installer is a resumable stage ladder. It publishes a complete checkout only after the repository is ready, and it records a compact result when a stage fails or is interrupted. A fresh install and the shared update completion path use the same product and command publication goal.
The normal order is:
- Check system prerequisites.
- Clone or refresh the Hermes source tree.
- Acquire the bootstrap Python and prepare the managed environment.
- Install locked dependencies and selected optional tools.
- Create the Hermes home and seed configuration files.
- Publish the
hermescommand and build selected products. - Offer interactive setup and gateway service installation.
- Write the completion record.
Non-interactive runs skip stages that need user input and leave those actions for hermes setup or hermes gateway install. The installer does not overwrite a non-Hermes destination. It parks local work before a branch move and keeps a rescue reference when a reset would otherwise lose local commits.
flowchart LR
A[Prerequisites] --> B[Source tree]
B --> C[Managed runtime]
C --> D[Configuration]
D --> E[Command and products]
E --> F[Setup and gateway]
F --> G[Completion record]
References: scripts/install.sh• L453-498 scripts/install.sh• L500-524 scripts/install.sh• L526-715 scripts/install.sh• L717-768 scripts/install.sh• L835-910 scripts/install.ps1• L780-794 scripts/install.ps1• L812-997 scripts/install.ps1• L999-1075
Release channels
Release channels decide which source or published release an install follows. Source installs default to the main branch. They can select a published stable or canary release for one run or persist that choice for the install. Packaged installs use the channel baked into their artifact and cannot change it through the source-install record.
Channel selection is per install, not per Hermes home. The record uses the canonical install path as its key, so a source checkout, desktop runtime, and gateway can share user data without changing each other’s feed. A branch option takes precedence over a channel because it is an explicit source target.
| Selection | Scope | Result |
|---|---|---|
--channel | One source update | Temporary channel choice |
--set-channel | One source install | Persisted channel choice |
--branch | One source update | Branch-tip update, overriding channel selection |
| Package or app identity | Packaged install | Fixed by the artifact owner |
Switching between canary and stable can change state compatibility. The CLI warns users to back up before a switch because a canary build may write state that an older stable build cannot read.
References: hermes_cli/update_channel.py• L1-29 hermes_cli/update_channel.py• L139-205 hermes_cli/update_channel.py• L208-226 hermes_cli/…/update.py• L77-107
Update staging and handoff
The update path is a transaction around a code move. It plans the target and running services, snapshots user state, applies the selected source or package action, prepares the new runtime, restarts services, verifies the result, and reports any work that remains. A read-only plan can show the install kind and service restart scope before mutation.
Before the checkout moves, the updater records enough information to restore the old tree if the process stops during a file move. It also checks that the target is the selected commit and validates critical startup files after the move. A syntax failure rolls the checkout back instead of leaving the CLI unable to start.
The old interpreter does not import the new application graph after the code move. The update writes a handoff request and runs the completion tail in a fresh interpreter from the new tree. This separates dependency and product work from stale in-memory modules. If the child cannot start, the update reports a manual continuation path while keeping the applied code and its recovery record visible.
sequenceDiagram
participant C as CLI process
participant S as State snapshot
participant T as Source tree
participant N as New interpreter
participant F as Service fleet
C->>C: Plan and preflight
C->>S: Capture quick or full backup
C->>T: Arm recovery and move to target
C->>T: Check target and startup files
C->>N: Hand off completion work
N->>N: Sync runtime and build products
N->>F: Drain, restart, and verify services
F-->>N: Return restart and health results
N-->>C: Write receipt and owed follow-ups
References: hermes_cli/…/update.py• L18-40 hermes_cli/update_cmd.py• L1092-1196 hermes_cli/update_cmd.py• L921-1001 hermes_cli/update_handoff.py• L32-47 hermes_cli/update_handoff.py• L127-153 hermes_cli/update_completion.py• L491-540
Service restart coordination
An update must move running Hermes services to the same code generation as the checkout. Restart coordination is fleet-wide but install-scoped: it finds gateways and serve runtimes owned by the active Hermes installation, drains active work where supported, restarts through the existing supervisor, and verifies the new process before claiming success.
The coordinator treats a multiplexed host gateway as one restart target even when it serves many profiles. It keeps systemd user and system scopes separate. A service that cannot be independently verified remains an owed restart rather than a false success. --no-gateway-restart deliberately defers this handoff for operators who restart the fleet separately.
When a restart phase fails, recovery starts a fresh interpreter. Gateway profiles use their normal per-profile restart command. systemd-owned serve and dashboard units are enumerated and checked by supervisor scope. Manual or desktop-owned runtimes are named as stale when the updater has no authority to relaunch them; the updater does not kill them merely to claim a clean result.
| Restart result | Meaning |
|---|---|
| Verified | Relaunch succeeded and the supervisor independently showed the new service active |
| Relaunch attempted | The command returned success but independent supervisor proof was unavailable |
| Failed | Relaunch, settle, or verification failed |
References: hermes_cli/update_cmd_fleet.py• L1675-1758 hermes_cli/update_restart_recovery.py• L12-35 hermes_cli/update_restart_recovery.py• L222-257 hermes_cli/update_restart_recovery.py• L352-386 hermes_cli/update_completion.py• L430-449 hermes_cli/…/update.py• L109-113
Backup and state protection
Backups protect the user home while code and dependencies change. The default pre-update safety net is a quick snapshot of critical state. A full mode adds a restorable ZIP archive of the Hermes home. Both modes use a shared backup slot and publish only complete staged output.
Quick snapshots focus on state that cannot be rebuilt, such as configuration, credentials, sessions, cron data, pairing data, and user stores. SQLite files are copied through a database-safe path. A failed or oversized database marks the snapshot incomplete and prevents pruning older snapshots that may be the only usable recovery source.
Full backups omit code, dependency trees, caches, and other regenerable content. They retain user data and selected external memory-provider files. hermes import checks the archive before writing, keeps machine-specific runtime files from the archive, restores databases with live-holder safeguards, and reports when older backup content reduces session or message counts.
| Mode | Protection | Main recovery action |
|---|---|---|
| Off | No pre-update snapshot | Use an existing backup or manual repair |
| Quick | Critical state files and profile snapshots | /snapshot list then /snapshot restore <id> |
| Full | Quick snapshot plus a home ZIP | hermes import <archive> |
References: hermes_cli/update_cmd_maint.py• L635-658 hermes_cli/update_cmd_maint.py• L686-714 hermes_cli/update_cmd_maint.py• L766-789 hermes_cli/backup.py• L1175-1180 hermes_cli/backup.py• L1197-1237 hermes_cli/backup.py• L1366-1454 hermes_cli/backup.py• L1498-1519 hermes_cli/backup_restore.py• L158-185 hermes_cli/backup_restore.py• L491-568
Diagnostics and repair
hermes doctor is the broad health check for an install. It combines configuration, runtime, service, tool, state database, profile, and connectivity checks into findings. Without --fix it reports the repair path. With --fix it applies only checks that have a safe local repair and leaves manual issues explicit.
Doctor checks state health without assuming that a live gateway is safe to stop or write over. It reports database holders, large WAL files, malformed schema, structural damage, configuration drift, stale channel records, missing dependencies, and service supervision problems. State database repair distinguishes an index or schema issue from canonical data damage; structural damage uses session recovery or a known backup instead of an unsafe in-place rebuild.
Windows launcher repair is part of early startup and update maintenance. It restores missing or obsolete command launchers outside the checkout and migrates old PATH entries only after the replacement launchers are proven present. This keeps a failed update from turning a temporary launcher rename into a full reinstall.
References: hermes_cli/doctor.py• L1-5 hermes_cli/doctor.py• L111-129 hermes_cli/doctor.py• L172-194 hermes_cli/doctor_state.py• L317-399 hermes_cli/doctor_state.py• L419-475 hermes_cli/doctor_config.py• L495-541 hermes_cli/_install_repair.py• L56-101 hermes_cli/_install_repair.py• L242-342
Recovery paths
Recovery is designed to run at the next Hermes launch as well as during the failed command. Startup checks durable update obligations before normal dispatch. It restores a torn checkout, resumes paused gateways, reports a fleet restart still owed, and rescues an orphaned Windows launcher when the surviving renamed file can be trusted.
The operator path depends on where the update stopped:
- If the code move was interrupted, launch Hermes again so the early recovery can restore or settle the checkout.
- If code changed but dependencies or product completion failed, rerun
hermes update; the receipt keeps the completion work visible. - If services remain on old code, use the restart guidance in the update receipt or run the gateway restart commands. A later launch retries owed service work.
- If user state is missing or damaged, restore the matching quick snapshot or import a verified full backup. Stop database holders when live-safe restore cannot prove ownership.
- If the code belongs to a sealed package or app, update through its steward instead of repeating
hermes update.
An update receipt records the stage result and follow-up obligations. A committed code move is not reported as a simple failed update when its completion or restart tail is still owed. This lets the next launch repair the remaining work without pretending that old services or an unverified database are healthy.
References: hermes_cli/main_install_repair.py• L189-249 hermes_cli/_early_recovery.py• L19-60 hermes_cli/update_cmd.py• L1092-1150 hermes_cli/update_cmd_fleet.py• L1592-1663 hermes_cli/update_restart_recovery.py• L12-21 hermes_cli/update_receipt.py• L180-218
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the installer stage manifest aligned with the stage ladder on both shell and PowerShell paths.
- Keep install stamps, steward classification, and update refusal commands aligned with every new package or app distribution.
- Keep channel records keyed per install so one checkout cannot change another install’s feed.
- Keep the pre-update snapshot file set aligned with every state store that code migration can replace or rewrite.
- Keep update handoff fields compatible with older released updaters and fresh-interpreter completion.
- Keep restart inventory, supervisor scope, and recovery result vocabulary aligned so an unverified service stays an owed follow-up.
- Keep launcher staging outside the mutable checkout and prove replacement launchers before removing legacy PATH entries.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
hermes update runs against a sealed app, image, Nix, or package tree | The wrong owner could mutate immutable or replaced code | Admission uses provenance and steward facts and returns the owner’s update path |
| Update stops during a checkout move | The source tree may contain a mixed generation | Durable move markers and early launch recovery restore or settle the tree |
| New code fails a critical startup check | The next CLI launch could be unusable | Post-move validation rolls back to the previous commit |
| Gateway restart succeeds only by command exit code | A stale interpreter can keep serving old code | Restart results require independent supervisor or process-generation proof |
| A pre-update snapshot misses a live database | State loss has no usable quick restore | SQLite-safe copy marks the snapshot incomplete and preserves older snapshots |
| Full archive contains corrupt members | Import could overwrite data before detecting damage | Import validates member data before publishing user files |
| Database restore runs while another process holds the file or WAL | Old and new processes can use different database images | Live-safe page restore is preferred; unsafe replacement fails closed |
| Windows launcher rename is interrupted | hermes may disappear from PATH | Startup rescues the sole quarantined launcher and reports manual recovery if it remains locked |
Key files
| File | Why to read it |
|---|---|
| scripts/install.sh | Defines the POSIX install ladder and shared completion goal |
scripts/install.ps1 | Defines the Windows install ladder and command publication ownership |
| hermes_cli/steward.py | Defines which system owns a sealed install |
| hermes_cli/update_contract.py | Defines update admission and refusal paths |
| hermes_cli/update_channel.py | Defines per-install release channel behavior |
| hermes_cli/update_cmd.py | Defines source update movement, validation, and rollback boundaries |
| hermes_cli/update_completion.py | Defines fresh-interpreter completion and final status handling |
| hermes_cli/update_cmd_fleet.py | Defines fleet-wide service restart coordination |
| hermes_cli/update_restart_recovery.py | Defines fresh-process restart recovery and verification outcomes |
| hermes_cli/backup.py | Defines quick snapshots and full backup creation |
| hermes_cli/backup_restore.py | Defines safe archive and SQLite restore behavior |
| hermes_cli/doctor.py | Defines the diagnostic check sequence and repair mode |
| hermes_cli/doctor_state.py | Defines state database health and repair guidance |
| hermes_cli/_install_repair.py | Defines Windows launcher repair and PATH migration |
| hermes_cli/main_install_repair.py | Defines startup recovery debts and dependency repair checks |