For a complete Hermes Agent move, install Hermes on the destination, run hermes backup on the source, transfer the resulting ~/hermes-backup-<timestamp>.zip, stop the destination gateway, run hermes import, and finish with hermes setup. A full archive carries Hermes data—including credentials—rather than the application runtime, so you must recreate the installation and treat the ZIP as a secret.
Antihost offers VPS plans with one-click Hermes Agent, NVMe storage and a 14-day free trial.
Which Hermes backup should you use?
Hermes provides three different portability choices. Select the one that matches what you are trying to protect before copying anything.
As an Amazon Associate I earn from qualifying purchases.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute| Method | Command | What it contains | Credentials | Best use |
|---|---|---|---|---|
| Full backup | hermes backup |
Configuration, credentials, memories, skills, sessions and profiles under the Hermes data root | Included; handle as a secret | Moving Hermes to another machine or performing a complete disaster-recovery restore |
| Quick snapshot | hermes backup --quick |
Selected critical state, including config.yaml, state.db, .env, authentication data and cron jobs |
Included where those files contain them | Frequent protection of critical state; not a complete machine migration |
| Single-profile archive | hermes profile export work ./work-backup.tar.gz |
The named profile’s configuration, memories, sessions and skills | Stripped from the archive | Porting or sharing one profile without transferring all profiles or secrets |
The full backup is a user-data archive, not a disk image. The NousResearch Hermes Agent FAQ describes it this way: “The full backup covers configuration, credentials, memories, skills, sessions, and profiles under the Hermes data root. It is not an application or runtime image.” You therefore reinstall Hermes and any required dependencies on the destination instead of expecting the ZIP to boot by itself.
What a full Hermes backup contains
Hermes stores its persistent data below ~/.hermes/. A normal full backup is intended to preserve the state that makes an installation feel like the same agent after restoration.
#1 Best Overall
- Easily store and access 2TB to content on the go with the Seagate Portable Drive, a USB external hard drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
- Configuration: the main
config.yamlfile and related settings. - Environment and authentication:
.envandauth.json, which can contain API keys, OAuth tokens or provider credentials. - Identity and behavior:
SOUL.md, profile data and the instructions that shape an agent. - Memories: the contents of
memories/. - Skills: installed user skills under
skills/. - Scheduled work: cron definitions in
cron/. - Conversation and operational history: sessions in
sessions/and logs inlogs/.
Because the archive can contain both long-lived secrets and private session history, copy it only to storage and machines you control. Encrypt it at rest, restrict file permissions, and avoid leaving an unprotected copy in a shared download folder or public cloud bucket.
What the full archive does not contain
A restore will not reproduce every byte on the source computer. The following items are deliberately outside the full-backup scope:
Free tools Windows power users keep installed
One-click scans. No signup required.
- The Hermes source checkout and its application code.
- Dependency environments, downloaded tools, models and other runtimes.
- Build caches, checkpoints and previous backups.
- Browser profiles.
- Python bytecode and SQLite sidecar files, which regenerate locally.
- Machine-local process markers such as
gateway.pid,cron.pidand.backup.lock.
Restore the package declarations and reinstall dependencies on the destination. Do not copy PID files to try to make an old process appear active; those files describe the old machine’s processes and are intentionally excluded. If your full-backup command reports files that could not be copied, read the skipped-file report before deleting the source installation or its data.
Full-machine migration: step by step
1. Prepare the destination installation
Install Hermes Agent on the replacement computer with the official installer before importing data. Use the same operating-system account, or choose an account whose home directory and permissions you understand. The default data location is ~/.hermes/; a different account will have a different home path.
Do not start a production gateway and immediately import over it. Finish the installation first, then perform the import while the destination gateway is stopped.
2. Create the source backup
On the machine that currently runs Hermes, open a shell as the account that owns the Hermes data and run:
Rank #2
- Easily store and access 5TB of content on the go with the Seagate portable drive, a USB external hard Drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
hermes backupUnless you specify another destination, Hermes writes a ZIP named like ~/hermes-backup-<timestamp>.zip. Keep the command’s completion output and note any skipped-file report. A successful command creates an archive, but a skipped-file warning still requires review because a missing file may affect a session, skill or other state you expected to move.
For a very large data root, wait for the command to finish before copying the ZIP. Copying a file that is still being written can produce an incomplete archive.
3. Transfer the ZIP securely
Move the completed archive to the destination by an encrypted transfer. The FAQ uses scp; for example, from the source machine you can copy the file to a destination account and host:
scp ~/hermes-backup-<timestamp>.zip destination-user@destination-host:~Replace the account, host and path with values for your environment. An external SSD is another transport option and can provide offline retention, but it must be encrypted or stored in a physically secure place because the ZIP contains credentials. After transfer, verify that the destination copy is complete before removing the source archive.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →4. Stop the destination gateway
Before importing, stop the Hermes gateway on the destination. Use the same service manager or launch command you use to run that gateway, and confirm that no Hermes gateway process remains connected to the data directory. The CLI reference specifically warns against importing while the gateway is running; an active process can read or write state while the restore is in progress.
5. Import into the destination data root
From the destination account, run:
hermes import ~/hermes-backup-<timestamp>.zipThe import writes restored data into the destination’s existing Hermes data area. It is not an operating-system restore: the destination application, dependencies, tools and runtimes remain the ones you installed in step 1.
Rank #3
- Easily store and access 1TB to content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop. Reformatting may be required for Mac
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
6. Reconnect providers and verify configuration
After the import completes, run:
hermes setupUse the setup flow to verify API keys and provider configuration. Even when .env and auth.json were restored, provider checks can expose a changed hostname, revoked token, different operating-system path or account-level permission issue. Correct those values before starting normal workloads.
7. Start the gateway and perform a functional check
Start the destination gateway only after the import and setup checks finish. Confirm, in a controlled test, that:
- The expected profile names are present.
- A recent session or memory can be opened.
- Skills load without missing-dependency errors.
- Scheduled jobs are present but will not run unexpectedly because of a changed timezone or path.
- The configured provider can authenticate and return a response.
Keep the source installation intact until these checks pass. A backup is a recovery mechanism, not proof that every file was copied successfully.
Moving only one Hermes profile
A profile archive is the safer choice when you need to port one agent and do not want to transfer every profile or credential. Export the profile on the source machine; this example uses a profile named work:
hermes profile export work ./work-backup.tar.gzTransfer work-backup.tar.gz to the destination, then import it under the desired profile name:
hermes profile import ./work-backup.tar.gz workThe archive carries that profile’s configuration, memories, sessions and skills. It strips credentials, so the destination will not inherit the source profile’s API keys or OAuth secrets. Re-authenticate each required provider on the destination and review any absolute paths that only exist on the source machine.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #4
- Easily store and access 4TB of content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Profile export is not equivalent to a full migration. It does not move unrelated profiles, global credentials or the complete Hermes data root. Conversely, a full ZIP is inappropriate for routine sharing because it includes secrets that a profile archive intentionally removes.
Using quick snapshots correctly
Run:
hermes backup --quickQuick mode creates a faster snapshot of selected critical state. The documented contents include config.yaml, state.db, .env, authentication data and cron jobs. It is useful when you want frequent protection between full backups—for example, after changing provider settings or scheduled jobs.
Do not use a quick snapshot as the only archive before replacing a computer. The FAQ explicitly says quick mode is not a replacement for a full backup before machine migration. It omits portions of the data root that a complete move may require, such as the full set of memories, skills, sessions and profiles.
Database and process safety during restore
Hermes uses SQLite’s backup API for safe copying while the application is running, including databases configured for WAL mode. That behavior helps the backup capture a consistent database state, but it does not make an import safe to perform against a live gateway.
During import, database members are written into the existing database file rather than replacing its inode. Open connections can therefore converge on the imported data instead of retaining a reference to an entirely new file. You still must stop the gateway: open connections may hold transactions, trigger concurrent writes or cause confusing results while other files are being restored.
After an import, start only one gateway instance for the restored data root. Old gateway.pid and cron.pid files are excluded from backups, so a missing PID file is expected and should not be “repaired” by copying one from the source.
Best Value
- Plug-and-play expandability
- SuperSpeed USB 3.2 Gen 1 (5Gbps)
Security checklist for Hermes archives
- Assume every full ZIP is compromised if an unauthorized person can read it; rotate affected API keys or OAuth credentials.
- Encrypt the archive before placing it on removable media or remote storage.
- Use an account and directory with restrictive permissions on both source and destination.
- Transfer over an encrypted channel such as the
scpworkflow used in the FAQ. - Delete temporary copies from shared folders, shell history transcripts and unencrypted external drives when the migration is complete.
- Keep at least one offline or otherwise isolated copy for disaster recovery, and record where it is stored.
- Do not upload a full backup to a support ticket or public issue; use a profile archive only when you need to share non-credential state.
Troubleshooting common migration failures
The import command cannot find the ZIP
Check the exact destination path and filename, including capitalization. List the home directory and pass an absolute path if the shell’s current directory is not what you expect. A timestamped filename is easy to mistype; copy it directly from the transfer output.
Hermes starts but providers fail authentication
Run hermes setup again and inspect the restored .env and auth.json values for expired tokens, changed provider endpoints or permissions. A profile archive never carries credentials, so profile imports always require fresh authentication.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesMemories, sessions or skills are missing
Confirm that you used hermes backup, not hermes backup --quick, for the migration. Review the full-backup skipped-file report. If only one profile was expected, verify that you imported the correct profile archive and name; a profile export intentionally excludes other profiles.
Import reports database or lock errors
Stop the destination gateway and any scheduled Hermes process, then retry the import. Remove only stale, destination-local lock or PID artifacts if your normal service procedure calls for it; never copy those files from the source machine. If another process continues to reopen the gateway, disable that service temporarily and confirm it is stopped before importing again.
Skills or tools fail after restoration
Reinstall dependencies, downloaded tools, models and runtimes on the destination. They are not part of the user-data archive. Check paths in configuration and skill files for references to directories that existed only on the source computer.
The source backup contains skipped files
Read the report and identify each skipped path. Keep the source installation and make a second backup after correcting permissions, closing files or freeing space as appropriate. Do not treat the ZIP as complete until the missing paths are either recovered separately or confirmed unnecessary.
A repeatable backup plan
For ongoing protection, combine the methods rather than choosing one forever:
- Use quick snapshots after important configuration, authentication or cron changes.
- Create a full backup before an operating-system upgrade, hardware replacement or major Hermes update.
- Copy the full ZIP to encrypted offline or access-controlled storage.
- Periodically test an import on a spare environment so you know the archive, credentials and dependencies can be restored.
- Retain the source installation until the destination passes profile, memory, skill, session and provider checks.
This approach separates frequent protection of critical state from the larger, less frequent archive needed for a genuine machine move. It also preserves a recovery path if a quick snapshot is too narrow or a full backup reports files it could not copy.
What to remember
Use a full hermes backup ZIP for a complete Hermes data migration, a quick snapshot only for critical-state protection, and a profile TAR.GZ when you need to move one agent without credentials. Reinstall Hermes and its dependencies on the destination, transfer archives securely, stop the destination gateway before importing, run hermes setup, and verify the restored installation before retiring the source.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
