Rename project to hermenix; convert host scripts to a Nu CLI

services.hermesVm -> services.hermenix throughout. setup.sh and
migrate-docker-hermes.sh are replaced by nu/hermenix.nu (setup + migrate
subcommands), packaged as a flake output (packages.${system}.hermenix,
pkgs.writers.writeNuBin) so it's installable without cloning conventions
beyond the repo itself. Both subcommands verified end-to-end against a
sandboxed dry run (stubbed disk/cache tools, a local ssh stand-in for the
migrate path) before landing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ariandClaude Sonnet 5 committed 2026-09-15 13:26:18 -04:00
1 parent 12227460fd
commit 2b33b98bae
10 files changed
+570 -568

No files matched your search

+39 -25
View File
@@ -1,4 +1,4 @@
# hermes-vm
# hermenix
Hermes Agent in a NixOS VM that owns its own bootloader and its own
`/nix/store`, on two btrfs-backed disks, under an unprivileged hardened QEMU.
@@ -13,10 +13,17 @@ so.
### Guided
The `hermenix` CLI (`nu/hermenix.nu`) is a flake package — no separate install
step, `nix run` builds and runs it directly from a checkout of this repo:
```bash
./setup.sh
nix run .#hermenix -- setup
```
(Or `nix profile install .#hermenix` once, then just `hermenix setup` from
here on. Either way, run it from this repo's root — it reads and writes
`guest/common.nix` relative to your current directory.)
Walks the host-side steps: checks prerequisites, creates the disks, generates
the cache signing key, fills in `guest/common.nix` from your SSH keys, builds
the bootstrap image and writes it to the disk. It prints the module snippet
@@ -29,8 +36,8 @@ and nothing destructive happens without an explicit confirmation. It keeps a
It deliberately stops short of `nixos-rebuild`, since that's your config.
The rest of this section is what the script does, for when you'd rather do it
by hand or something goes sideways.
The rest of this section is what the command does, for when you'd rather do
it by hand or something goes sideways.
### 1. Create the disks
@@ -110,19 +117,19 @@ sudo dd if=result/nixos.img of=/var/lib/hermes-vm/system/system.raw \
```nix
{
inputs.hermes-vm.url = "path:/etc/nixos/hermes-vm";
inputs.hermenix.url = "path:/etc/nixos/hermenix";
outputs = { nixpkgs, hermes-vm, ... }: {
outputs = { nixpkgs, hermenix, ... }: {
nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ hermes-vm.nixosModules.default ./configuration.nix ];
modules = [ hermenix.nixosModules.default ./configuration.nix ];
};
};
}
```
```nix
services.hermesVm = {
services.hermenix = {
enable = true;
disk.baseDir = "/var/lib/hermes-vm";
network.externalInterface = "eno1"; # your uplink
@@ -251,7 +258,7 @@ scratch.
## Managing Hermes from the host
`hermes-vm` drives the virtual machine. `hermes-ctl` drives the agent inside
it. Rename the latter with `services.hermesVm.cliName = "hermes";` if you'd
it. Rename the latter with `services.hermenix.cliName = "hermes";` if you'd
rather it felt local.
```bash
@@ -290,7 +297,7 @@ there's no declarative option for them.
If `status` and `logs` come back empty, the gateway unit is probably named
something other than `hermes-agent`. Run `hermes-ctl units` and set
`services.hermesVm.gatewayUnit` to match; upstream has used more than one
`services.hermenix.gatewayUnit` to match; upstream has used more than one
name for it.
## Seeing what the guest is running
@@ -324,7 +331,7 @@ By default the guest can reach the public internet and nothing private. To
open a single endpoint — say Ollama on another machine:
```nix
services.hermesVm.lanAccess = [
services.hermenix.lanAccess = [
{ address = "192.168.1.50"; port = 11434; } # ollama
{ address = "192.168.1.50"; port = 9000; proto = "udp"; }
];
@@ -343,7 +350,7 @@ design is that an agent which goes wrong can't go wandering.
Different chain, different option. ComfyUI on the host, port 8188:
```nix
services.hermesVm.hostAccess = [ { port = 8188; } ];
services.hermenix.hostAccess = [ { port = 8188; } ];
```
**The service must be bound somewhere the guest can see.** If it listens
@@ -379,7 +386,7 @@ curl http://10.77.0.2:8080
To publish it to the wider network:
```nix
services.hermesVm.publish = [
services.hermenix.publish = [
{ hostPort = 8080; guestPort = 8080; }
];
```
@@ -443,7 +450,7 @@ lspci -Dnn | grep -i vga # addresses and vendor:device IDs
```
```nix
services.hermesVm.passthrough = {
services.hermenix.passthrough = {
iommu = "amd"; # or "intel"
pci = [
{ address = "0000:01:00.0"; id = "10de:2204"; } # graphics
@@ -484,7 +491,7 @@ lsusb # e.g. "Bus 001 Device 004: ID 8087:0026 Intel ..."
```
```nix
services.hermesVm.passthrough.usb = [
services.hermenix.passthrough.usb = [
{ vendorId = "8087"; productId = "0026"; } # bluetooth radio
{ vendorId = "0403"; productId = "6001"; } # serial adapter
];
@@ -538,7 +545,7 @@ hermes-vm backups
### Snapshots
Hourly by default, keeping 48. Only the state disk — the system disk isn't
snapshotted because `setup.sh` rebuilds it from the flake in minutes.
snapshotted because `hermenix setup` rebuilds it from the flake in minutes.
The host fsfreezes the guest through qemu-guest-agent around each one, so the
snapshot captures a consistent filesystem rather than the equivalent of
@@ -557,7 +564,7 @@ they're pruned.
### Backups
```nix
services.hermesVm.backup = {
services.hermenix.backup = {
enable = true;
repository = "sftp:backup@nas:/hermes";
passwordFile = "/var/lib/secrets/hermes-restic";
@@ -578,10 +585,10 @@ the *host*, so it needs no `lanAccess` entry — the guest never touches it.
### When the guest won't boot at all
The system disk is disposable by design. Re-run `setup.sh`, write a fresh
image to the system disk, and leave the state disk alone — Hermes comes back
with its identity, memories, workspace and NixOS config intact. That is the
intended repair, not a last resort.
The system disk is disposable by design. Re-run `hermenix setup`, write a
fresh image to the system disk, and leave the state disk alone — Hermes comes
back with its identity, memories, workspace and NixOS config intact. That is
the intended repair, not a last resort.
---
@@ -660,10 +667,17 @@ secrets into your host's store.
If you already have a running Hermes with real data (`HERMES_HOME` pointing
at some directory full of `SOUL.md`, `memories/`, `sessions/`, `state.db`,
etc.), see `migrate-docker-hermes.sh`. It copies — never moves or deletes —
the source data, so the original stays a safe fallback until you've verified
the new VM.
etc.):
The module's `services.hermesVm.hermesHome` option lets `hermes-ctl` (and
```bash
nix run .#hermenix -- migrate /path/to/existing/HERMES_HOME
```
Run `nix run .#hermenix -- migrate --help` for the full set of options
(vsock CID, guest user, destination path, hostname rewrites). It copies —
never moves or deletes — the source data, so the original stays a safe
fallback until you've verified the new VM.
The module's `services.hermenix.hermesHome` option lets `hermes-ctl` (and
your own `HERMES_HOME` export inside the guest) point at wherever that
existing flat layout lands, instead of the default seeded `~/.hermes`.