Files
2026-10-10 22:06:12 -04:00

4.8 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.

Snapshots run hourly by default (systemd timer with OnCalendar = "hourly") and keep the last 48. They only cover the state disk. See RECOVERY.md for details and how to adjust services.hermenix.snapshots.interval / keep.

Btrfs + nodatacow design note. The state disk image is stored on a btrfs subvolume with chattr +C (nodatacow). This is intentional: CoW under a VM disk image causes terrible fragmentation. However, a btrfs snapshot of a nodatacow subvolume re-enables CoW for any blocks the snapshot still references. Live snapshots therefore increase fragmentation and the amount of data that later changes (affecting both guest performance and backup size). Snapshots and backups are independent; pruning snapshots improves both. See RECOVERY.md and RECOVERY.md for retention advice and why backups are file-level tars over vsock rather than disk images.

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"