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

99 lines
3.9 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.
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"
```