114 lines
4.8 KiB
Markdown
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"
|
|
```
|