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/ … orhermenix ctl pull. - Machine facts (not identity):
/etc/hermes/ENVIRONMENT.md, regenerated every guest rebuild fromguest/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(fromguest/common.nix). - No guest
nix.settings/nix.gc;determinate-nixdcollects. - Substituters: FlakeHub Cache → host cache →
cache.nixos.org. - Do not set
inputs.nixpkgs.followsondeterminate(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"