# Manual setup What `hermenix setup` does, step by step, for hand-running or when something goes sideways. Prefer the guided command in [INSTALL.md](INSTALL.md) when you can. ## 1. Create the disks Two disks — design in [CONCEPTS.md](CONCEPTS.md#two-disks). ```bash sudo btrfs subvolume create /var/lib/hermes-vm/system sudo btrfs subvolume create /var/lib/hermes-vm/state sudo mkdir -p /var/lib/hermes-vm/snapshots # BEFORE creating any file inside them sudo chattr +C /var/lib/hermes-vm/system /var/lib/hermes-vm/state sudo btrfs property set /var/lib/hermes-vm/system compression none sudo btrfs property set /var/lib/hermes-vm/state compression none sudo truncate -s 80G /var/lib/hermes-vm/system/system.raw sudo truncate -s 20G /var/lib/hermes-vm/state/state.raw sudo mkfs.ext4 -L hermes-state /var/lib/hermes-vm/state/state.raw ``` **`chattr +C` ordering matters.** Btrfs CoW stacked under a VM disk image fragments badly. `+C` disables that — but only for files created _after_. Set it on empty subvolumes and confirm with `lsattr` before writing anything. Wrong order → recreate the subvolume and copy the image in fresh. Separate subvolumes so a btrfs snapshot of state does not include the system image. ## 2. Generate the cache signing key The host serves its store to the guest as a read-only binary cache. ```bash sudo mkdir -p /var/lib/secrets sudo nix-store --generate-binary-cache-key hermes-cache-1 \ /var/lib/secrets/hermes-cache.secret /var/lib/secrets/hermes-cache.pub sudo chown nix-serve /var/lib/secrets/hermes-cache.secret sudo chmod 0400 /var/lib/secrets/hermes-cache.secret cat /var/lib/secrets/hermes-cache.pub ``` ## 3. Write `/etc/hermenix/local.nix` Host-specific settings live here, not in this repo — see `guest/local.nix.example`: ```nix { cachePublicKey = "hermes-cache-1:AbCd..."; # key you just printed; empty = skip host cache authorizedKeys = [ "ssh-ed25519 AAAA... you@laptop" ]; } ``` `sudo mkdir -p /etc/hermenix` first if needed. ## 4. Build the image and write it to the system disk `--impure` is required because `guest/common.nix` reads `/etc/hermenix/local.nix` outside the flake source tree. The extra substituter flags avoid compiling Determinate Nix from source. `setup` also passes `--no-write-lock-file --refresh` when building from the git URL — mirror that if you're doing the same by hand. ```bash nix build --impure --no-write-lock-file --refresh \ git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermes-guest-image \ --option extra-substituters https://install.determinate.systems \ --option extra-trusted-public-keys cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM= # notrunc keeps the disk at its full size; the image is smaller sudo dd if=result/nixos.img of=/var/lib/hermes-vm/system/system.raw \ bs=4M conv=notrunc,fsync status=progress ``` From a local checkout, use `.` instead of the git URL (still `--impure`). ## 5. Module + first boot Continue from [INSTALL.md](INSTALL.md#add-the-module).