Files
2026-10-09 14:35:12 -04:00

4.1 KiB

CLI reference

One binary, hermenix:

For
hermenix setup host provisioning — disks, cache key, image
hermenix migrate <src> existing flat HERMES_HOME → guest
hermenix migrate connections connection files only
hermenix remote <host> "<cmd>" setup/migrate over SSH
hermenix vm <sub> VM lifecycle, snapshots, backups
hermenix ctl <sub> host-side bridge into the guest (files, unit, passthrough)
hermenix version packaged version string

Quote multi-word remote/passthrough args as one string — CONCEPTS.md.

Setup: INSTALL.md. Migrate: MIGRATE.md.


hermenix vm

hermenix vm ssh                       # interactive shell (vsock)
hermenix vm ssh "systemctl status"    # run a command and exit
hermenix vm console                   # journalctl -u hermes-vm -f (read-only)
hermenix vm start | stop | restart

hermenix vm config                    # guest generation, history, git status
hermenix vm config-pull [dir]         # copy guest /etc/nixos here

hermenix vm snapshot | snapshots
hermenix vm rollback <snap>           # type 'rollback' to confirm

hermenix vm backup | backups

console is follow-only (no input). No interactive fallback if the guest is dead.

Repo guest/ is the seed; live guest /etc/nixos diverges after the agent edits it. config-pull is for reading/diffing — a host rebuild will not fix a guest config problem.


hermenix ctl

Host-side helpers over vsock. They know where Hermes's files live in this VM layout and how to reach the gateway unit — they are not a second Hermes manual. For Hermes features (chat, sessions, providers, skills, …) use the upstream CLI or Hermes Agent docs; unknown ctl words are passed through to hermes in the guest.

# Files under hermesHome (default /var/lib/hermes/.hermes)
hermenix ctl soul [edit]
hermenix ctl memory [edit]         # memories/USER.md if present
hermenix ctl conf [edit]           # config.yaml
hermenix ctl secrets [edit|show]   # .env, mode 0600; masked by default

# Gateway user unit (name: services.hermenix.gatewayUnit)
hermenix ctl status | logs | restart
hermenix ctl units

# Seed / fold-back (destructive where noted)
hermenix ctl reseed                # overwrite from /etc/nixos/hermes seed
hermenix ctl pull [dir]            # live home → host (no .env/sessions/state.db)

Passthrough examples (Hermes's own commands):

hermenix ctl chat
hermenix ctl update
hermenix ctl "sessions list"
hermenix ctl doctor

edit pulls over vsock, opens local $EDITOR, writes back, offers restart. Secrets never enter the Nix store — no declarative option for them.

If status/logs are empty, check hermenix ctl units and set services.hermenix.gatewayUnit to the real unit name.

services.hermenix.hermesHome is where ctl looks. Override for a flat migrated layout; export HERMES_HOME inside the guest for the gateway process if it differs from the default.


Env baked in by the host module

Env Option Default
HERMES_VSOCK_CID services.hermenix.vsockCid 77
HERMES_GUEST_NAME services.hermenix.name hermes
HERMES_DISK_BASE_DIR services.hermenix.disk.baseDir /var/lib/hermes-vm
HERMES_HOME_DIR services.hermenix.hermesHome /var/lib/hermes/.hermes
HERMES_GATEWAY_UNIT services.hermenix.gatewayUnit hermes-agent