Files
hermenix/docs/MIGRATE.md
T
2026-10-09 14:35:12 -04:00

75 lines
2.6 KiB
Markdown

# Migrate an existing deployment
Copy an existing flat `HERMES_HOME` into the guest after hermenix setup + host
`nixos-rebuild` and `hermenix vm ssh true` work:
```bash
nix run git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermenix -- \
migrate /path/to/existing/HERMES_HOME
```
`migrate --help` for vsock CID, guest user, `--dest`, hostname rewrites.
**Copy only — never move or delete the source** until the new side is verified.
Remote: [INSTALL.md](INSTALL.md#remote-host) — put `migrate /path/...` in the
quoted command string.
What a `HERMES_HOME` contains and how Hermes uses it is upstream territory —
[Hermes Agent](https://github.com/NousResearch/hermes-agent). This page is only the hermenix carry path.
## `hermesHome`
`services.hermenix.hermesHome` is where `hermenix ctl` looks in the guest.
| Layout | Value |
| -------------------------- | -------------------------------------------- |
| Seeded `.hermes` (default) | `/var/lib/hermes/.hermes` |
| Flat at state root | `migrate --dest` (default `/var/lib/hermes`) |
Export `HERMES_HOME` inside the guest to the same path for the gateway process.
## Don't use `sudo`
`migrate` uses your user's ssh-over-vsock key (same as `authorizedKeys`).
`sudo` → root has no key → `Permission denied (publickey)`. If
`hermenix vm ssh` works as you, run `migrate` the same way.
## `hermenix migrate connections`
Connection/integration files only (no identity wipe), local or `--to-guest`:
```bash
hermenix migrate connections /old/HERMES_HOME ./staging
hermenix migrate connections /old/HERMES_HOME --to-guest
```
Defaults: files `config.yaml`, `auth.json`, `.env`; dir `connections/`.
Rewrites apply in the destination only.
## Troubleshooting
### Unreadable source entries
Rootless-Docker leftovers may be unreadable; `tar --ignore-failed-read` makes
that non-fatal. Pull those paths as root separately if needed:
```bash
sudo tar -C /path/to/HERMES_HOME/.hermes -cf - . \
| hermenix vm ssh 'mkdir -p /var/lib/hermes/.hermes-old && tar -C /var/lib/hermes/.hermes-old -xf -'
```
### Stale Docker launcher after an old migrate
Current `migrate` excludes `.local/bin` and `.hermes-installed`. If an older
run left a Docker-routing `~/.local/bin/hermes` ("docker not found on PATH"):
```bash
rm -f ~/.local/bin/hermes ~/.hermes-installed
sudo systemctl start hermes-install # or reinstall per upstream docs
journalctl -fu hermes-install
```
Then finish Hermes configuration with the upstream CLI
([docs](https://github.com/NousResearch/hermes-agent)), not with hermenix-specific steps.