Back Up and Migrate a Hermes Installation

Hermes supports two different portability boundaries. A full backup captures the whole Hermes home for machine recovery, while a profile export packages one agent profile for safer transfer or sharing.

Official documentation: https://hermes-agent.nousresearch.com/docs/reference/faq

CLI reference: https://hermes-agent.nousresearch.com/docs/reference/cli-commands

Choose the right archive

Use hermes backup for a complete installation snapshot, including profiles, configuration, sessions, skills, and credentials. Protect the resulting ZIP as sensitive material. Restore it with hermes import <archive> on the target machine.

Use hermes profile export for a single profile. Profile exports are designed to omit credentials, which makes them better for distribution, but the target will need provider authentication and may need machine-specific paths adjusted.

Backup checklist

Decide whether the recovery unit is the full installation or one profile.
Store full backups in encrypted, access-controlled storage.
Record the Hermes version and platform with the archive.
Verify archive integrity before deleting the source.
Keep credentials out of profile distributions.
Review absolute paths, terminal backends, and service definitions after restore.
Re-authenticate revoked or machine-bound OAuth providers.
Test sessions, tools, memory, cron, and gateways on the target.

Pitfalls

Sending a full backup as if it were a credential-free profile package.
Assuming a copied service PID or runtime file should remain active on the target.
Restoring paths that do not exist on the new operating system.
Deleting the source before the target passes an end-to-end test.
Treating archive creation as proof the archive can be restored.

Verification steps

Create the selected backup or profile export.
Inspect archive type, size, permissions, and checksum.
Restore into a disposable profile or test machine first.
Run hermes doctor and hermes version.
Confirm sessions and skills are present.
Reconfigure provider credentials without printing them.
Test one tool call and one gateway message, then document any path changes.