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

114 lines
4.8 KiB
Markdown

# 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](RECOVERY.md#snapshots)
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](RECOVERY.md#snapshots) and [RECOVERY.md](RECOVERY.md#backups)
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](https://github.com/NousResearch/hermes-agent). 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](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:
```bash
hermenix remote fwdesk.lab.internal "setup --clean"
hermenix vm ssh "systemctl status"
hermenix ctl "sessions list"
```