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:
1 parent
12227460fd
commit
2b33b98bae
10 files changed
+570
-568
No files matched your search
@@ -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`.
|
||||
Reference in new issue
Block a user