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

3.9 KiB

Concepts

Shared model for everything else in these docs. Read once; other pages assume it.

Two disks

Holds Size (default) Snapshotted Backed up
system NixOS, /nix/store 80G No No
state identity, workspace, /etc/nixos, Hermes home 20G Yes Yes

System is large, churny, rebuildable from this flake. State holds what cannot be reproduced — snapshots stay cheap.

Host images under services.hermenix.disk.baseDir (default /var/lib/hermes-vm):

$baseDir/system/system.raw
$baseDir/state/state.raw
$baseDir/snapshots/

Guest: state disk at /var/lib/hermes. Hermes home defaults to /var/lib/hermes/.hermes (~/.hermes for user hermes). /etc/nixos → /var/lib/hermes/nixos.

What belongs inside Hermes home (SOUL, memories, skills, sessions, …) is defined by Hermes itself — see upstream docs. hermenix only decides which disk it lives on and that the seed is applied once.

The boundary is the host

The guest owns its kernel and config. Nothing inside the guest is a security boundary; modules/host.nix nftables are. QEMU runs as unprivileged hermes-vm with seccomp + systemd hardening. Thin device model: virtio-blk, virtio-net, vsock, RNG, serial. No virtiofs. vhost-net off on purpose.

Default
Public internet Yes
Host Nix cache Yes, one port; hostCache.enable = false closes it
Anything else on the host No, unless hostAccess
LAN / other VMs No, unless lanAccess
Inbound from the network No, unless publish (NAT mode)
Host hardware None, unless passthrough

network.bridged = true: LAN inbound = every port the guest opens; publish ignored. Outbound gates unchanged. NETWORK.md.

Seed once

guest/hermes/ is a template copied into the guest on first boot only (/var/lib/hermes/.seeded):

guest/hermes/
  home/          →  ~/.hermes   (SOUL.md, config.yaml, skills/, …)
  workspace/     →  ~/workspace

Hermes owns and rewrites its home after that — re-seeding on every rebuild would wipe learned state. hermenix consequences:

  • Editing guest/hermes/ post-first-boot does nothing alone → hermenix ctl reseed (destructive; needs fresh confirmation).
  • Live files: hermenix ctl soul / conf / … or hermenix ctl pull.
  • Machine facts (not identity): /etc/hermes/ENVIRONMENT.md, regenerated every guest rebuild from guest/common.nix.

vsock, not network SSH

Host → guest (vm ssh, ctl, backups) uses vsock (default CID 77). No management SSH port on the network path.

ssh -o ProxyCommand='socat - VSOCK-CONNECT:<cid>:22' hermes@hermes

Determinate Nix in the guest

Guest: Determinate Nix, nixpkgs on FlakeHub. Host: stock Nix.

  • Do not edit /etc/nix/nix.conf — custom settings in /etc/nix/nix.custom.conf (from guest/common.nix).
  • No guest nix.settings / nix.gc; determinate-nixd collects.
  • Substituters: FlakeHub Cache → host cache → cache.nixos.org.
  • Do not set inputs.nixpkgs.follows on determinate (cache misses).

Quote multi-word subcommands

nu treats bare --flag tokens as flags on the outer command. Quote anything past a single bare word:

hermenix remote fwdesk.lab.internal "setup --clean"
hermenix vm ssh "systemctl status"
hermenix ctl "sessions list"