Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / cli-installation-update-and-recovery

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 shapeCode ownerUpdate path
Git source checkoutHermes CLIhermes update
Desktop app bundleDesktop appDesktop app update controls
Docker imageImage or deployment toolPull and replace the image
Nix store pathNixFlake or profile rebuild
Termux packageAPT package managerpkg upgrade hermes-agent
Commit build or other external treeBuilder or external stewardObtain 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:

  1. Check system prerequisites.
  2. Clone or refresh the Hermes source tree.
  3. Acquire the bootstrap Python and prepare the managed environment.
  4. Install locked dependencies and selected optional tools.
  5. Create the Hermes home and seed configuration files.
  6. Publish the hermes command and build selected products.
  7. Offer interactive setup and gateway service installation.
  8. 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.

SelectionScopeResult
--channelOne source updateTemporary channel choice
--set-channelOne source installPersisted channel choice
--branchOne source updateBranch-tip update, overriding channel selection
Package or app identityPackaged installFixed 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 resultMeaning
VerifiedRelaunch succeeded and the supervisor independently showed the new service active
Relaunch attemptedThe command returned success but independent supervisor proof was unavailable
FailedRelaunch, 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.

ModeProtectionMain recovery action
OffNo pre-update snapshotUse an existing backup or manual repair
QuickCritical state files and profile snapshots/snapshot list then /snapshot restore <id>
FullQuick snapshot plus a home ZIPhermes 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:

  1. If the code move was interrupted, launch Hermes again so the early recovery can restore or settle the checkout.
  2. If code changed but dependencies or product completion failed, rerun hermes update; the receipt keeps the completion work visible.
  3. 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.
  4. 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.
  5. 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

TriggerConsequenceGuard
hermes update runs against a sealed app, image, Nix, or package treeThe wrong owner could mutate immutable or replaced codeAdmission uses provenance and steward facts and returns the owner’s update path
Update stops during a checkout moveThe source tree may contain a mixed generationDurable move markers and early launch recovery restore or settle the tree
New code fails a critical startup checkThe next CLI launch could be unusablePost-move validation rolls back to the previous commit
Gateway restart succeeds only by command exit codeA stale interpreter can keep serving old codeRestart results require independent supervisor or process-generation proof
A pre-update snapshot misses a live databaseState loss has no usable quick restoreSQLite-safe copy marks the snapshot incomplete and preserves older snapshots
Full archive contains corrupt membersImport could overwrite data before detecting damageImport validates member data before publishing user files
Database restore runs while another process holds the file or WALOld and new processes can use different database imagesLive-safe page restore is preferred; unsafe replacement fails closed
Windows launcher rename is interruptedhermes may disappear from PATHStartup rescues the sole quarantined launcher and reports manual recovery if it remains locked

Key files

FileWhy to read it
scripts/install.shDefines the POSIX install ladder and shared completion goal
scripts/install.ps1Defines the Windows install ladder and command publication ownership
hermes_cli/steward.pyDefines which system owns a sealed install
hermes_cli/update_contract.pyDefines update admission and refusal paths
hermes_cli/update_channel.pyDefines per-install release channel behavior
hermes_cli/update_cmd.pyDefines source update movement, validation, and rollback boundaries
hermes_cli/update_completion.pyDefines fresh-interpreter completion and final status handling
hermes_cli/update_cmd_fleet.pyDefines fleet-wide service restart coordination
hermes_cli/update_restart_recovery.pyDefines fresh-process restart recovery and verification outcomes
hermes_cli/backup.pyDefines quick snapshots and full backup creation
hermes_cli/backup_restore.pyDefines safe archive and SQLite restore behavior
hermes_cli/doctor.pyDefines the diagnostic check sequence and repair mode
hermes_cli/doctor_state.pyDefines state database health and repair guidance
hermes_cli/_install_repair.pyDefines Windows launcher repair and PATH migration
hermes_cli/main_install_repair.pyDefines startup recovery debts and dependency repair checks