doc clean
This commit is contained in:
1 parent
c2a7f94821
commit
30427e3975
34 files changed
+1119
-1758
No files matched your search
@@ -0,0 +1,98 @@
|
||||
# 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"
|
||||
```
|
||||
Reference in new issue
Block a user