Keeping Portable Hermes Updated

Keeping Portable Hermes Updated

Portable Hermes includes a tested snapshot of Hermes Agent. The upstream NousResearch/hermes-agent project changes frequently—sometimes daily—but you decide when to adopt those changes.

There are two independent update channels:

Update channel	Source	What it updates	Best use
Portable Hermes distribution	aivrar/portable-hermes-agent	Windows launchers, integrations, portable tools, dependencies, and the Hermes version tested with this distribution	Normal maintenance; recommended for everyone
Upstream Hermes Agent	NousResearch/hermes-agent	Newer core Hermes Agent code, while restoring the Portable Hermes integration files afterward	Optional access to the newest upstream features and fixes

Running one updater does not automatically run the other.

Recommended Update Sequence

For the clearest and safest result:

1. Finish or save any active Hermes work.
2. Close Hermes windows and any running Hermes gateways.
3. Run UPDATE.bat from the extracted Portable Hermes folder.
4. Start Hermes again.
5. If you want newer upstream changes, ask Hermes to check first and then update.
6. Restart Hermes after a successful upstream update.

This order establishes the current Portable-tested baseline first, then optionally advances the upstream core.

1. Update the Portable Distribution

Close Hermes and double-click:

UPDATE.bat

The equivalent command is:

hermes.bat update --backup --yes

What this updater does

• Updates from aivrar/portable-hermes-agent
• Creates pre-update backups when --backup is used (UPDATE.bat uses the safe update path)
• Updates the Portable launchers, integrations, dependencies, UI assets, and tested Hermes source baseline
• Preserves local runtime data such as .hermes/, .hermes/custom_tools/, .hermes/extensions/, extensions/, and python_embedded/
• Validates the updated installation and tells you if a locked file or another problem needs attention

It works with both Git checkouts and downloaded release ZIPs. A Git checkout updates through Git. A release ZIP downloads the latest Portable repository archive and overlays it while keeping the protected runtime folders.

When to run it

• When a new Portable Hermes release is announced
• When a fix or security update is published
• When a maintainer asks you to update before troubleshooting
• Every one or two weeks as a simple routine, if you want to stay current

You do not need to run it every day.

2. Check or Update Upstream Hermes Agent

This optional updater runs from inside Hermes and uses the agent tools check_hermes_updates and update_hermes.

To check without installing anything, ask:

Check whether upstream Hermes Agent has updates. Do not install anything yet.

If you want the update, ask:

Update upstream Hermes Agent while preserving Portable Hermes. When finished, tell me whether I should restart.

Hermes can inspect the situation, explain how far behind it is when Git history is available, perform the update, restore the Portable-specific integration files, and report the result.

Git checkout versus release ZIP

• Git checkout: the checker can fetch upstream metadata and report the exact ahead/behind count. The updater creates a backup branch by default, temporarily protects local changes, updates the core, and restores the Portable-specific files.
• Downloaded release ZIP: there is no .git history, so the checker cannot calculate an exact commit count. It reports ZIP-overlay mode instead. The updater can still download the latest upstream source archive, overlay it, and preserve the protected Portable paths.

The ZIP message does not mean the updater is broken; it only means exact Git history is unavailable in that installation.

Restart after an upstream update

Restart Hermes after a successful upstream update. The currently running Python process already loaded the old modules, so a restart is what activates the newly installed code throughout the application.

The upstream updater updates source code; it is not a replacement for the Portable updater's full dependency installation, UI build, validation, and distribution maintenance.

How Often Should I Check?

Your preference	Suggested routine
Stable and low-maintenance	Run UPDATE.bat for announced Portable releases, fixes, and security notices
Normally current	Run UPDATE.bat every one or two weeks; check upstream about weekly
Newest upstream changes	Check upstream whenever you like, even daily; install only when you are ready to restart and verify your workflows

Upstream may change daily, but that does not make your installed snapshot immediately obsolete or unsafe. The Portable release is meant to remain usable as shipped.

What Happens If I Run the Portable Updater Later?

The Portable updater installs the Hermes source baseline tested with the current Portable distribution. If you had previously moved the core to a newer upstream version, a later Portable update may return those source files to that tested baseline.

That is intentional. If you prefer the newest upstream code, finish the Portable update, start Hermes, check upstream again, install the optional upstream update, and restart.

Quick Answers

Do I have to use both updaters?

No. The Portable updater is the normal maintenance path. The upstream updater is optional.

Can I check upstream without changing files?

Yes. Ask Hermes to check and explicitly say not to install anything yet.

Can I update while Hermes is open?

Run the upstream updater from one active Hermes session, but close other Hermes windows and gateways first. Run UPDATE.bat after closing Hermes completely.

Will an update erase my settings or custom tools?

Both update paths are designed to preserve the documented Portable runtime folders and integration files. Keeping a separate backup of irreplaceable personal data is still good practice.

Which updater should I run first?

Run the Portable updater first, then optionally check and install upstream Hermes changes.

If an update reports a locked file, close all Hermes processes and gateways, then retry. See Troubleshooting for more help.