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
@@ -8,9 +8,9 @@ Key non-negotiable rules from that file:
|
||||
|
||||
- **Always present a plan first** and wait for user approval before making any
|
||||
changes — no matter how small the task.
|
||||
- **Never run builds or disk-writing steps** (`nix build`, `./setup.sh`'s disk
|
||||
creation/image-write steps, `dd` to any disk image, `nixos-rebuild switch`
|
||||
on any consuming host) — zero exceptions, even if asked.
|
||||
- **Never run builds or disk-writing steps** (`nix build`, `hermenix setup`'s
|
||||
disk creation/image-write steps, `dd` to any disk image, `nixos-rebuild
|
||||
switch` on any consuming host) — zero exceptions, even if asked.
|
||||
- Never run `hermes-vm rollback` or `hermes-ctl reseed` without explicit,
|
||||
freshly-given confirmation — both destroy live guest state.
|
||||
- Never edit `guest/hardware.nix`'s disk labels without the operator having
|
||||
|
||||
+23
-18
@@ -1,4 +1,4 @@
|
||||
# Agent Guidelines — hermex
|
||||
# Agent Guidelines — hermenix
|
||||
|
||||
Rules and best practices for any AI agent working in this repository.
|
||||
Read this file before making any changes.
|
||||
@@ -16,7 +16,7 @@ Your plan must include:
|
||||
1. **What** you intend to change (files, modules, seed content)
|
||||
2. **Why** the change is needed
|
||||
3. **How** you will do it (which files you will edit, in what order)
|
||||
4. **What you will NOT do** (e.g., "I will not run setup.sh or build the image")
|
||||
4. **What you will NOT do** (e.g., "I will not run hermenix setup or build the image")
|
||||
|
||||
Only after the user approves the plan may you proceed with edits.
|
||||
|
||||
@@ -31,25 +31,28 @@ Only after the user approves the plan may you proceed with edits.
|
||||
```
|
||||
nix build
|
||||
nix flake check
|
||||
./setup.sh # unless the user is actively running it themselves with you watching
|
||||
hermenix setup # unless the user is actively running it themselves with you watching
|
||||
hermenix migrate # same — it writes into a live guest
|
||||
dd ... of=/var/lib/hermes-vm/** # writing any disk image
|
||||
nixos-rebuild switch / test / build (on any host consuming this flake)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
|
||||
- `setup.sh` creates/writes disk images and generates host secrets (a binary
|
||||
cache signing key) — destructive if repeated carelessly, and it's the
|
||||
operator's host, not yours to act on.
|
||||
- `hermenix setup` creates/writes disk images and generates host secrets (a
|
||||
binary cache signing key) — destructive if repeated carelessly, and it's
|
||||
the operator's host, not yours to act on.
|
||||
- `hermenix migrate` writes into a running guest and rewrites its config,
|
||||
even though it never touches the migration source.
|
||||
- A `nixos-rebuild switch` on a consuming host is a live, production-affecting
|
||||
action — for `hl-fwdesk` specifically, it's the machine running the
|
||||
operator's actual daily-use Hermes deployment.
|
||||
- These commands can take a long time and consume real resources on a
|
||||
machine you don't control from here.
|
||||
|
||||
**Your job:** Write good Nix and good docs. The operator runs `setup.sh`, the
|
||||
image build, and any `nixos-rebuild` themselves, on the host, watching each
|
||||
step.
|
||||
**Your job:** Write good Nix, good Nu, and good docs. The operator runs
|
||||
`hermenix setup`, `hermenix migrate`, the image build, and any
|
||||
`nixos-rebuild` themselves, on the host, watching each step.
|
||||
|
||||
### ❌ NEVER run `hermes-vm rollback` or `hermes-ctl reseed` without fresh confirmation
|
||||
|
||||
@@ -74,9 +77,9 @@ after. Real credentials belong in the guest's own `~/.hermes/.env`
|
||||
|
||||
### ❌ NEVER move or delete source data during a migration
|
||||
|
||||
When carrying over an existing Hermes deployment (see
|
||||
`migrate-docker-hermes.sh`), only ever read from and copy the source. Leave
|
||||
it in place and untouched until the operator has verified the new deployment
|
||||
When carrying over an existing Hermes deployment (see `nu/hermenix.nu`'s
|
||||
`migrate` subcommand), only ever read from and copy the source. Leave it in
|
||||
place and untouched until the operator has verified the new deployment
|
||||
end-to-end. This is the rollback safety net — don't remove it.
|
||||
|
||||
### ❌ NEVER commit or push unless explicitly asked
|
||||
@@ -93,6 +96,9 @@ These are always safe to perform without asking:
|
||||
- Reading any file in this repo
|
||||
- Editing `modules/host.nix` to add/adjust options (gated behind `mkIf
|
||||
cfg.enable`, following the existing style)
|
||||
- Editing `nu/hermenix.nu` — check any change by parsing it (`nu
|
||||
nu/hermenix.nu --help` and `nu nu/hermenix.nu <subcommand> --help` parse
|
||||
the whole file without running any subcommand body) before handing it back
|
||||
- Editing `guest/hermes/home` / `guest/hermes/workspace` template seed content
|
||||
(as long as it stays free of real secrets — see above)
|
||||
- Editing `README.md` / `GUIDELINES.md` / `AGENTS.md`
|
||||
@@ -110,11 +116,10 @@ don't run it.** Describe what you would do and ask.
|
||||
## Repository Layout
|
||||
|
||||
```
|
||||
hermex/
|
||||
├── flake.nix # bootstrap flake: builds the guest image, exposes nixosModules.default
|
||||
├── modules/host.nix # services.hermesVm — the host-side NixOS module
|
||||
├── setup.sh # guided host-side setup (disks, cache key, image build)
|
||||
├── migrate-docker-hermes.sh # carries an existing flat HERMES_HOME into a hermex guest
|
||||
hermenix/
|
||||
├── flake.nix # bootstrap flake: builds the guest image + the hermenix CLI package, exposes nixosModules.default
|
||||
├── modules/host.nix # services.hermenix — the host-side NixOS module
|
||||
├── nu/hermenix.nu # the hermenix CLI: `setup` (guided host-side setup) and `migrate` (carry over existing data)
|
||||
├── guest/
|
||||
│ ├── flake.nix # the GUEST's own /etc/nixos flake — belongs to the agent, not the operator
|
||||
│ ├── common.nix # guest NixOS config baked into the bootstrap image
|
||||
@@ -122,5 +127,5 @@ hermex/
|
||||
│ └── hermes/
|
||||
│ ├── home/ # template seed -> ~/.hermes on first boot (SOUL.md, config.yaml, memories/, skills/)
|
||||
│ └── workspace/ # template seed -> ~/workspace on first boot
|
||||
└── README.md # full usage docs
|
||||
└── README.md # full usage docs
|
||||
```
|
||||
@@ -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`.
|
||||
@@ -1,17 +1,9 @@
|
||||
{
|
||||
description = "Hermes Agent in a self-managing NixOS VM, two-disk btrfs-backed, under hardened QEMU";
|
||||
description = "hermenix — Hermes Agent in a self-managing NixOS VM, two-disk btrfs-backed, under hardened QEMU";
|
||||
|
||||
inputs = {
|
||||
# nixpkgs from FlakeHub, so the guest's artifacts come from FlakeHub Cache.
|
||||
# "0.1" is rolling (the nixos-unstable equivalent); use "0" for current
|
||||
# stable instead.
|
||||
nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.1";
|
||||
|
||||
# Determinate Nix. Note the deliberate absence of inputs.nixpkgs.follows
|
||||
# here: Determinate warn that making this flake follow your nixpkgs causes
|
||||
# cache misses for artifacts that would otherwise come from FlakeHub Cache.
|
||||
determinate.url = "https://flakehub.com/f/DeterminateSystems/determinate/3";
|
||||
|
||||
nixos-generators = {
|
||||
url = "github:nix-community/nixos-generators";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
@@ -22,21 +14,50 @@
|
||||
{ self, nixpkgs, determinate, nixos-generators, ... }@inputs:
|
||||
let
|
||||
system = "x86_64-linux";
|
||||
pkgs = nixpkgs.legacyPackages.${system};
|
||||
in
|
||||
{
|
||||
nixosModules.default = ./modules/host.nix;
|
||||
|
||||
# One-time bootstrap image. See the README: building this needs two extra
|
||||
# substituter flags so you aren't compiling Determinate Nix yourself.
|
||||
packages.${system}.hermes-guest-image = nixos-generators.nixosGenerate {
|
||||
inherit system;
|
||||
format = "raw-efi";
|
||||
modules = [
|
||||
determinate.nixosModules.default
|
||||
./guest/common.nix
|
||||
];
|
||||
};
|
||||
packages.${system} = {
|
||||
# One-time bootstrap image. See the README: building this needs two
|
||||
# extra substituter flags so you aren't compiling Determinate Nix
|
||||
# yourself.
|
||||
hermes-guest-image = nixos-generators.nixosGenerate {
|
||||
inherit system;
|
||||
format = "raw-efi";
|
||||
modules = [
|
||||
determinate.nixosModules.default
|
||||
./guest/common.nix
|
||||
];
|
||||
};
|
||||
|
||||
packages.${system}.default = self.packages.${system}.hermes-guest-image;
|
||||
# The host-side CLI: `hermenix setup` (guided disk/cache/image setup)
|
||||
# and `hermenix migrate <source>` (carry over an existing flat
|
||||
# HERMES_HOME). A Nu script, wrapped so its external dependencies are
|
||||
# always on PATH regardless of what the host happens to have
|
||||
# installed.
|
||||
hermenix = pkgs.writers.writeNuBin "hermenix"
|
||||
{
|
||||
makeWrapperArgs = [
|
||||
"--prefix"
|
||||
"PATH"
|
||||
":"
|
||||
(pkgs.lib.makeBinPath (with pkgs; [
|
||||
openssh
|
||||
socat
|
||||
gnutar
|
||||
gnused
|
||||
btrfs-progs
|
||||
e2fsprogs
|
||||
coreutils
|
||||
nix
|
||||
]))
|
||||
];
|
||||
}
|
||||
(builtins.readFile ./nu/hermenix.nu);
|
||||
|
||||
default = self.packages.${system}.hermenix;
|
||||
};
|
||||
};
|
||||
}
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
let
|
||||
# These must match services.hermesVm.* on the host. If you changed the
|
||||
# These must match services.hermenix.* on the host. If you changed the
|
||||
# defaults there, change them here too before building the image.
|
||||
hostAddress = "10.77.0.1";
|
||||
guestAddress = "10.77.0.2";
|
||||
|
||||
@@ -52,6 +52,6 @@ networking.firewall.allowedTCPPorts = [ 22 8080 ];
|
||||
```
|
||||
|
||||
Reaching further — a LAN device, another host, or being reachable from
|
||||
outside — needs an operator-side change to `services.hermesVm.*`
|
||||
outside — needs an operator-side change to `services.hermenix.*`
|
||||
(`lanAccess`, `hostAccess`, `publish`). You cannot grant yourself that from
|
||||
in here, on purpose. Ask rather than looking for a way around it.
|
||||
@@ -1,111 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Carry an existing, already-running Hermes deployment (e.g. the
|
||||
# nousresearch/hermes-agent Docker image, HERMES_HOME bind-mounted from the
|
||||
# host) into a hermex guest VM, preserving its exact flat layout.
|
||||
#
|
||||
# This is written for the hl-fwdesk migration specifically (see the REWRITE
|
||||
# list below) but the mechanics generalize: point SOURCE at any existing flat
|
||||
# HERMES_HOME, adjust the rewrite rules for your own network, and run it.
|
||||
#
|
||||
# SAFETY: this script only ever READS from SOURCE. It never deletes or moves
|
||||
# anything there — the original stays a fully intact fallback. If anything
|
||||
# goes wrong after this, `sudo nixos-rebuild switch --rollback` on the host
|
||||
# restores the previous (e.g. Docker) deployment pointed at the same,
|
||||
# untouched source data.
|
||||
#
|
||||
# Run this AFTER:
|
||||
# - setup.sh has built and written the guest image
|
||||
# - the host's nixos-rebuild has brought up the hermes-vm and it has booted
|
||||
# at least once (so the state disk is formatted and mounted)
|
||||
# - `hermes-vm ssh true` succeeds
|
||||
#
|
||||
# Usage:
|
||||
# ./migrate-docker-hermes.sh /var/lib/hermes
|
||||
#
|
||||
# What it does:
|
||||
# 1. Confirms with you before touching anything.
|
||||
# 2. Tars SOURCE (read-only) and streams it into the guest over the
|
||||
# existing vsock SSH channel, landing at DEST_IN_GUEST (default
|
||||
# /var/lib/hermes, i.e. the root of the guest's state disk — matching
|
||||
# services.hermesVm.hermesHome = DEST_IN_GUEST on the host).
|
||||
# 3. Rewrites the known-stale Docker/LAN hostnames in the migrated config
|
||||
# files to addresses the guest can actually reach.
|
||||
#
|
||||
# It does NOT install Hermes, start the gateway, or touch secrets/hermes-env.age
|
||||
# — those steps are manual, documented in README.md and the plan that
|
||||
# produced this script.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
VSOCK_CID="${VSOCK_CID:-77}"
|
||||
GUEST_USER="${GUEST_USER:-hermes}"
|
||||
DEST_IN_GUEST="${DEST_IN_GUEST:-/var/lib/hermes}"
|
||||
|
||||
SOURCE="${1:-}"
|
||||
[ -n "$SOURCE" ] || { echo "usage: $0 <source-hermes-home-dir>" >&2; exit 1; }
|
||||
[ -d "$SOURCE" ] || { echo "error: $SOURCE is not a directory" >&2; exit 1; }
|
||||
|
||||
SSH=(ssh
|
||||
-o ProxyCommand="socat - VSOCK-CONNECT:${VSOCK_CID}:22"
|
||||
-o StrictHostKeyChecking=accept-new
|
||||
"${GUEST_USER}@hermes")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Rewrite rules applied to the migrated config after it lands in the guest.
|
||||
# These are specific to the hl-fwdesk migration — edit for your own setup.
|
||||
#
|
||||
# host.docker.internal / fwdesk.lab.internal both resolved to hl-fwdesk
|
||||
# itself under Docker; the guest reaches the same host at its bridge address.
|
||||
# castle.hub.internal is a *different* LAN device (Home Assistant) reached
|
||||
# via lanAccess instead.
|
||||
# ---------------------------------------------------------------------------
|
||||
REWRITE_FILES=(config.yaml auth.json context_length_cache.yaml .env)
|
||||
REWRITE_FROM=(host.docker.internal fwdesk.lab.internal castle.hub.internal)
|
||||
REWRITE_TO=(10.77.0.1 10.77.0.1 10.0.12.1)
|
||||
|
||||
echo "Source (read-only): $SOURCE"
|
||||
echo "Destination (guest): ${GUEST_USER}@hermes:${DEST_IN_GUEST} (over vsock, cid ${VSOCK_CID})"
|
||||
echo
|
||||
echo "This will:"
|
||||
echo " 1. tar '$SOURCE' (not modifying it) and stream it into the guest"
|
||||
echo " 2. rewrite these hostnames in the migrated config, in the guest only:"
|
||||
for i in "${!REWRITE_FROM[@]}"; do
|
||||
echo " ${REWRITE_FROM[$i]} -> ${REWRITE_TO[$i]}"
|
||||
done
|
||||
echo
|
||||
read -r -p "Type 'migrate' to proceed: " confirm
|
||||
[ "$confirm" = "migrate" ] || { echo "aborted"; exit 1; }
|
||||
|
||||
echo
|
||||
echo "== confirming guest is reachable =="
|
||||
"${SSH[@]}" true
|
||||
|
||||
echo "== streaming $SOURCE -> guest:${DEST_IN_GUEST} (this can take a while for 8G+) =="
|
||||
tar -C "$SOURCE" -cf - . | "${SSH[@]}" "mkdir -p '${DEST_IN_GUEST}' && tar -C '${DEST_IN_GUEST}' -xf -"
|
||||
|
||||
echo "== rewriting stale hostnames in the guest =="
|
||||
for f in "${REWRITE_FILES[@]}"; do
|
||||
path="${DEST_IN_GUEST}/${f}"
|
||||
sed_expr=""
|
||||
for i in "${!REWRITE_FROM[@]}"; do
|
||||
sed_expr+="s#${REWRITE_FROM[$i]}#${REWRITE_TO[$i]}#g; "
|
||||
done
|
||||
"${SSH[@]}" "[ -f '$path' ] && sed -i '$sed_expr' '$path' && echo ' rewrote $f' || echo ' $f not present, skipping'"
|
||||
done
|
||||
|
||||
echo
|
||||
echo "Done. The original at $SOURCE is untouched."
|
||||
echo
|
||||
echo "Next, inside the guest (hermes-vm ssh):"
|
||||
echo " export HERMES_HOME=${DEST_IN_GUEST}"
|
||||
echo " # then the usual install steps from README.md:"
|
||||
echo " # determinate-nixd login"
|
||||
echo " # sudo nix flake lock /etc/nixos"
|
||||
echo " # curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash"
|
||||
echo " # hermes setup"
|
||||
echo " # hermes gateway install"
|
||||
echo
|
||||
echo "Then verify with hermes-ctl status / logs before considering the old"
|
||||
echo "deployment retired. Decrypt secrets/hermes-env.age yourself and fold"
|
||||
echo "anything relevant into ${DEST_IN_GUEST}/.env (hermes-ctl secrets edit)."
|
||||
+9
-9
@@ -2,7 +2,7 @@
|
||||
|
||||
let
|
||||
inherit (lib) mkOption mkEnableOption mkIf types optionalString;
|
||||
cfg = config.services.hermesVm;
|
||||
cfg = config.services.hermenix;
|
||||
net = cfg.network;
|
||||
|
||||
vmUser = "hermes-vm";
|
||||
@@ -41,7 +41,7 @@ let
|
||||
'';
|
||||
in
|
||||
{
|
||||
options.services.hermesVm = {
|
||||
options.services.hermenix = {
|
||||
enable = mkEnableOption "the Hermes Agent VM";
|
||||
|
||||
name = mkOption {
|
||||
@@ -67,7 +67,7 @@ in
|
||||
description = ''
|
||||
Directory holding the guest's disk images. On btrfs this should be
|
||||
laid out as three subvolumes - system/, state/ and snapshots/ - with
|
||||
nodatacow set. setup.sh does this for you.
|
||||
nodatacow set. `hermenix setup` does this for you.
|
||||
'';
|
||||
};
|
||||
|
||||
@@ -370,7 +370,7 @@ in
|
||||
layout under the state disk mount. Override this when carrying over
|
||||
an existing flat HERMES_HOME from elsewhere (e.g. a prior Docker
|
||||
deployment) that you're placing directly at the root of the state
|
||||
disk instead of under .hermes - see migrate-docker-hermes.sh.
|
||||
disk instead of under .hermes - see `hermenix migrate --help`.
|
||||
|
||||
This only changes where the host-side hermes-ctl wrapper (soul,
|
||||
memory, conf, secrets, reseed, pull) looks. It does not change what
|
||||
@@ -390,16 +390,16 @@ in
|
||||
assertions = [
|
||||
{
|
||||
assertion = net.externalInterface != null;
|
||||
message = "services.hermesVm.network.externalInterface must be set.";
|
||||
message = "services.hermenix.network.externalInterface must be set.";
|
||||
}
|
||||
{
|
||||
assertion = cfg.backup.enable -> (cfg.backup.repository != "");
|
||||
message = "services.hermesVm.backup.repository must be set when backups are enabled.";
|
||||
message = "services.hermenix.backup.repository must be set when backups are enabled.";
|
||||
}
|
||||
{
|
||||
assertion = anyPci -> (pt.iommu != null);
|
||||
message = ''
|
||||
services.hermesVm.passthrough.pci needs passthrough.iommu set to
|
||||
services.hermenix.passthrough.pci needs passthrough.iommu set to
|
||||
"intel" or "amd". Without the IOMMU, a passed-through device can
|
||||
read host memory directly and the VM boundary is meaningless.
|
||||
'';
|
||||
@@ -429,7 +429,7 @@ in
|
||||
preStart = ''
|
||||
for img in ${systemImage} ${stateImage}; do
|
||||
if [ ! -e "$img" ]; then
|
||||
echo "$img is missing. Run ./setup.sh first." >&2
|
||||
echo "$img is missing. Run 'hermenix setup' first." >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
@@ -716,7 +716,7 @@ in
|
||||
# Snapshots of the state disk only.
|
||||
#
|
||||
# The system disk is not snapshotted on purpose. It is large, it is where
|
||||
# all the write churn happens, and setup.sh can rebuild it from the flake
|
||||
# all the write churn happens, and `hermenix setup` can rebuild it from the flake
|
||||
# in minutes. Snapshotting it would cost a lot and buy nothing.
|
||||
# =====================================================================
|
||||
systemd.services.hermes-vm-snapshot = mkIf cfg.snapshots.enable {
|
||||
|
||||
+453
@@ -0,0 +1,453 @@
|
||||
#!/usr/bin/env nu
|
||||
#
|
||||
# hermenix — host-side tooling for the Hermes Agent VM.
|
||||
#
|
||||
# Two subcommands:
|
||||
# hermenix setup guided host-side setup: disks, cache signing
|
||||
# key, guest/common.nix, build + write the image
|
||||
# hermenix migrate <source> carry an existing flat HERMES_HOME (e.g. from
|
||||
# a prior Docker deployment) into a running
|
||||
# guest, unchanged
|
||||
#
|
||||
# Neither runs `nixos-rebuild` — that stays yours to run, watching it happen.
|
||||
|
||||
# ---------------------------------------------------------------- output ---
|
||||
|
||||
def say [msg: string] { print $" ($msg)" }
|
||||
def note [msg: string] { print $" (ansi dark_gray)($msg)(ansi reset)" }
|
||||
def ok [msg: string] { print $" (ansi green)✓(ansi reset) ($msg)" }
|
||||
def warn [msg: string] { print $" (ansi yellow)!(ansi reset) ($msg)" }
|
||||
def die [msg: string] { print -e $"\n(ansi red)error:(ansi reset) ($msg)"; exit 1 }
|
||||
def step [n: int, title: string] { print $"\n(ansi attr_bold)== ($n). ($title)(ansi reset)" }
|
||||
|
||||
def ask [prompt: string, default: string = ""] {
|
||||
let suffix = if $default != "" { $" [($default)]" } else { "" }
|
||||
let reply = (input $" ($prompt)($suffix): ")
|
||||
if $reply == "" { $default } else { $reply }
|
||||
}
|
||||
|
||||
def confirm [prompt: string] {
|
||||
let reply = (input $" ($prompt) [y/N] ")
|
||||
($reply | str downcase | str starts-with "y")
|
||||
}
|
||||
|
||||
def confirm-word [word: string, prompt: string] {
|
||||
(input $" ($prompt) ") == $word
|
||||
}
|
||||
|
||||
# Run a command, sudo-prefixed unless already root (set once via
|
||||
# $env.HERMENIX_NEED_SUDO at the top of `main setup`). Fails loudly, like any
|
||||
# other external command, if the command fails.
|
||||
def priv [...args: string] {
|
||||
let need_sudo = ($env.HERMENIX_NEED_SUDO? | default false)
|
||||
let argv = if $need_sudo { ["sudo"] ++ $args } else { $args }
|
||||
^($argv | first) ...($argv | skip 1)
|
||||
}
|
||||
|
||||
# Same, but captures stdout/exit code instead of failing the script.
|
||||
def priv-out [...args: string] {
|
||||
let need_sudo = ($env.HERMENIX_NEED_SUDO? | default false)
|
||||
let argv = if $need_sudo { ["sudo"] ++ $args } else { $args }
|
||||
(^($argv | first) ...($argv | skip 1) | complete)
|
||||
}
|
||||
|
||||
def main [] {
|
||||
print "usage: hermenix <subcommand> ..."
|
||||
print ""
|
||||
print " hermenix setup guided host-side setup"
|
||||
print " hermenix migrate <source> carry an existing flat HERMES_HOME into the guest"
|
||||
print ""
|
||||
print "run `hermenix <subcommand> --help` for details on either."
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------ setup ---
|
||||
|
||||
# Guided host-side setup: disks, cache signing key, guest/common.nix, build
|
||||
# and write the bootstrap image. Safe to re-run — every step checks what's
|
||||
# already done and offers to skip. Never runs nixos-rebuild.
|
||||
def "main setup" [] {
|
||||
$env.HERMENIX_NEED_SUDO = ((^id -u | str trim) != "0")
|
||||
|
||||
let common = "guest/common.nix"
|
||||
let cache_name = "hermes-cache-1"
|
||||
let secret_key = "/var/lib/secrets/hermes-cache.secret"
|
||||
let public_key = "/var/lib/secrets/hermes-cache.pub"
|
||||
let determinate_sub = "https://install.determinate.systems"
|
||||
let determinate_key = "cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM="
|
||||
|
||||
print $"(ansi attr_bold) hermenix · guided setup(ansi reset)"
|
||||
note "This prepares the host. It does not run nixos-rebuild — you'll paste a"
|
||||
note "module snippet into your own configuration at the end."
|
||||
|
||||
step 1 "Checking prerequisites"
|
||||
if not ("flake.nix" | path exists) or not ($common | path exists) {
|
||||
die "run this from the hermenix repository root"
|
||||
}
|
||||
if (which nix | is-empty) { die "nix not found on PATH" }
|
||||
if (do -i { ^nix flake --help } | complete).exit_code != 0 {
|
||||
die "flakes are not enabled. Add 'experimental-features = nix-command flakes' to /etc/nix/nix.conf"
|
||||
}
|
||||
ok "nix with flakes"
|
||||
|
||||
if (which btrfs | is-empty) { die "btrfs-progs not found. Snapshots need it." }
|
||||
if (which mkfs.ext4 | is-empty) { die "mkfs.ext4 not found (e2fsprogs)" }
|
||||
ok "btrfs-progs"
|
||||
|
||||
if not ("/dev/kvm" | path exists) {
|
||||
die "/dev/kvm is missing. KVM is required; check virtualisation is enabled in firmware."
|
||||
}
|
||||
ok "kvm"
|
||||
|
||||
if (which nixos-version | is-empty) {
|
||||
warn "this host does not look like NixOS — the module expects NixOS"
|
||||
} else {
|
||||
let ver = ((^nixos-version | complete).stdout | str trim | split row " " | first)
|
||||
ok $"host is NixOS \(($ver)\)"
|
||||
}
|
||||
|
||||
step 2 "Guest disks"
|
||||
note "Two disks, deliberately:"
|
||||
note " system - NixOS and the Nix store. Big, churny, rebuildable. Not backed up."
|
||||
note " state - identity, memories, workspace, /etc/nixos. Small. Snapshotted."
|
||||
|
||||
let base = ask "Directory for the disk images" "/var/lib/hermes-vm"
|
||||
|
||||
let parent = ($base | path dirname)
|
||||
let fstype = ((do -i { ^stat -f -c "%T" $parent } | complete).stdout | str trim)
|
||||
let use_btrfs = if $fstype != "btrfs" {
|
||||
warn $"($parent) is ($fstype), not btrfs"
|
||||
warn "snapshots need btrfs. Everything else works; you'd rely on backups alone."
|
||||
if not (confirm "Continue anyway?") { die "aborted" }
|
||||
false
|
||||
} else {
|
||||
true
|
||||
}
|
||||
|
||||
priv mkdir "-p" $base
|
||||
|
||||
def make-subvol [path: string, use_btrfs: bool] {
|
||||
let exists = ($use_btrfs and (do -i { priv btrfs subvolume show $path } | complete).exit_code == 0)
|
||||
if $use_btrfs and not $exists {
|
||||
do -i { priv rmdir $path } | complete | ignore
|
||||
priv btrfs subvolume create $path | ignore
|
||||
priv chattr +C $path
|
||||
do -i { priv btrfs property set $path compression none } | complete | ignore
|
||||
ok $"subvolume ($path) \(nodatacow\)"
|
||||
} else {
|
||||
priv mkdir "-p" $path
|
||||
}
|
||||
}
|
||||
make-subvol $"($base)/system" $use_btrfs
|
||||
make-subvol $"($base)/state" $use_btrfs
|
||||
priv mkdir "-p" $"($base)/snapshots"
|
||||
|
||||
let system_img = $"($base)/system/system.raw"
|
||||
let state_img = $"($base)/state/state.raw"
|
||||
|
||||
let system_existed = ((priv-out test "-f" $system_img).exit_code == 0)
|
||||
if $system_existed {
|
||||
let sz = ((priv-out du "-h" "--apparent-size" $system_img).stdout | str trim | split column "\t" | get column0.0)
|
||||
ok $"system disk exists \(($sz)\)"
|
||||
} else {
|
||||
let syssize = ask "System disk size" "80G"
|
||||
priv truncate "-s" $syssize $system_img
|
||||
if $use_btrfs {
|
||||
let attrs = (priv-out lsattr "-l" $system_img).stdout
|
||||
if ($attrs | str contains "No_COW") {
|
||||
ok "system disk created, nodatacow confirmed"
|
||||
} else {
|
||||
warn $"system disk created but nodatacow did NOT apply - check 'lsattr ($system_img)'"
|
||||
}
|
||||
} else {
|
||||
ok "system disk created"
|
||||
}
|
||||
}
|
||||
|
||||
if (priv-out test "-f" $state_img).exit_code == 0 {
|
||||
let sz = ((priv-out du "-h" "--apparent-size" $state_img).stdout | str trim | split column "\t" | get column0.0)
|
||||
ok $"state disk exists \(($sz)\)"
|
||||
} else {
|
||||
let statesize = ask "State disk size" "20G"
|
||||
priv truncate "-s" $statesize $state_img
|
||||
priv mkfs.ext4 "-q" "-L" hermes-state $state_img
|
||||
ok "state disk created and formatted (label: hermes-state)"
|
||||
}
|
||||
|
||||
step 3 "Binary cache signing key"
|
||||
note "The host serves its store to the guest read-only, so the guest doesn't"
|
||||
note "re-download from the internet what you already have."
|
||||
|
||||
let key_existed = (priv-out test "-f" $secret_key).exit_code == 0
|
||||
if $key_existed {
|
||||
ok "signing key already exists"
|
||||
} else {
|
||||
priv mkdir "-p" /var/lib/secrets
|
||||
priv nix-store "--generate-binary-cache-key" $cache_name $secret_key $public_key
|
||||
priv chmod 0400 $secret_key
|
||||
ok $"generated ($cache_name)"
|
||||
}
|
||||
let cache_pub = ((priv-out cat $public_key).stdout | str trim)
|
||||
say $"Public key: (ansi dark_gray)($cache_pub)(ansi reset)"
|
||||
|
||||
if (do -i { ^id nix-serve } | complete).exit_code == 0 {
|
||||
priv chown nix-serve $secret_key
|
||||
ok "key owned by nix-serve"
|
||||
} else {
|
||||
warn "the nix-serve user does not exist yet — that's normal on a first run"
|
||||
note "after your nixos-rebuild, run:"
|
||||
note $" sudo chown nix-serve ($secret_key)"
|
||||
}
|
||||
|
||||
step 4 "SSH access to the guest"
|
||||
let common_lines = (open $common | lines)
|
||||
let ak_start = ($common_lines | enumerate | where item == " authorizedKeys = [" | get index | get 0?)
|
||||
let current_keys = if $ak_start != null {
|
||||
let ak_end_rel = ($common_lines | skip ($ak_start + 1) | enumerate | where item == " ];" | get index | get 0)
|
||||
($common_lines | slice ($ak_start + 1)..($ak_start + $ak_end_rel) | where {|l| $l | str trim | str starts-with '"ssh-' } | length)
|
||||
} else {
|
||||
0
|
||||
}
|
||||
|
||||
let replace_keys = if $current_keys > 0 {
|
||||
ok $"($current_keys) key\(s\) already configured in ($common)"
|
||||
confirm "Replace them?"
|
||||
} else {
|
||||
true
|
||||
}
|
||||
|
||||
mut selected_keys = []
|
||||
if $replace_keys {
|
||||
let found = (glob $"($env.HOME)/.ssh/*.pub")
|
||||
if ($found | length) > 0 {
|
||||
say "Public keys found in ~/.ssh:"
|
||||
for pair in ($found | enumerate) {
|
||||
let comment = (open $pair.item | str trim | split row " " | skip 2 | str join " ")
|
||||
note $" ($pair.index + 1)) ($pair.item | path basename) — ($comment)"
|
||||
}
|
||||
let pick = ask "Numbers to use (space separated, or 'n' to paste one)" "1"
|
||||
if $pick != "n" {
|
||||
for n in ($pick | split row " ") {
|
||||
let idx = ($n | into int) - 1
|
||||
if $idx < 0 or $idx >= ($found | length) {
|
||||
die $"no such option: ($n)"
|
||||
}
|
||||
$selected_keys = ($selected_keys | append (open ($found | get $idx) | str trim))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if ($selected_keys | is-empty) {
|
||||
let pasted = ask "Paste a public key (blank to skip)"
|
||||
if $pasted != "" { $selected_keys = [$pasted] }
|
||||
}
|
||||
|
||||
if ($selected_keys | is-empty) {
|
||||
warn "no SSH key set — you'll only be able to reach the guest with 'hermes-vm console'"
|
||||
}
|
||||
}
|
||||
|
||||
step 5 $"Writing ($common)"
|
||||
if not ($"($common).bak" | path exists) {
|
||||
cp $common $"($common).bak"
|
||||
note $"original saved as ($common).bak"
|
||||
}
|
||||
|
||||
mut lines = (open $common | lines)
|
||||
# cachePublicKey
|
||||
$lines = ($lines | each {|l|
|
||||
if ($l | str starts-with " cachePublicKey = ") {
|
||||
$" cachePublicKey = \"($cache_pub)\";"
|
||||
} else {
|
||||
$l
|
||||
}
|
||||
})
|
||||
ok "cachePublicKey set"
|
||||
|
||||
# authorizedKeys block
|
||||
if not ($selected_keys | is-empty) {
|
||||
let start = ($lines | enumerate | where item == " authorizedKeys = [" | get index.0)
|
||||
let end_rel = ($lines | skip ($start + 1) | enumerate | where item == " ];" | get index.0)
|
||||
let end = $start + 1 + $end_rel
|
||||
let new_key_lines = ($selected_keys | each {|k| $" \"($k)\"" })
|
||||
$lines = (($lines | slice 0..$start) ++ $new_key_lines ++ ($lines | slice $end..(($lines | length) - 1)))
|
||||
ok $"authorizedKeys set \(($selected_keys | length) key\(s\)\)"
|
||||
}
|
||||
$lines | str join "\n" | save -f $common
|
||||
|
||||
step 6 "Building the bootstrap image"
|
||||
note "The extra substituter flags stop you compiling Determinate Nix yourself."
|
||||
mut built = false
|
||||
if (confirm "Build now? (first run can take a while)") {
|
||||
^nix build .#hermes-guest-image --option extra-substituters $determinate_sub --option extra-trusted-public-keys $determinate_key
|
||||
ok "built"
|
||||
$built = true
|
||||
} else {
|
||||
say "Skipped. Run manually:"
|
||||
note " nix build .#hermes-guest-image \\"
|
||||
note $" --option extra-substituters ($determinate_sub) \\"
|
||||
note $" --option extra-trusted-public-keys ($determinate_key)"
|
||||
}
|
||||
|
||||
step 7 "Writing the bootstrap image to the system disk"
|
||||
let images = (glob "result/*.img")
|
||||
if ($images | is-empty) {
|
||||
warn "no image found under ./result - skipping"
|
||||
note "build it, then:"
|
||||
note $" sudo dd if=result/nixos.img of=($system_img) bs=4M conv=notrunc,fsync status=progress"
|
||||
} else {
|
||||
let image = ($images | first)
|
||||
let img_bytes = (ls $image | get size.0 | into int)
|
||||
let vol_bytes = ((priv-out stat "-c" "%s" $system_img).stdout | str trim | into int)
|
||||
say $"image: ($image) \((($img_bytes / 1024 / 1024) | math floor) MiB\)"
|
||||
say $"target: ($system_img) \((($vol_bytes / 1024 / 1024 / 1024) | math floor) GiB\)"
|
||||
if $img_bytes > $vol_bytes { die "image is larger than the system disk" }
|
||||
|
||||
if $system_existed {
|
||||
warn "the system disk already existed. Writing the image replaces the"
|
||||
warn "guest OS. Hermes's identity and memories live on the STATE disk and"
|
||||
warn "are untouched, but anything it installed outside /var/lib/hermes is lost."
|
||||
}
|
||||
|
||||
if (confirm-word "overwrite" "Type 'overwrite' to write the image:") {
|
||||
priv dd $"if=($image)" $"of=($system_img)" "bs=4M" "conv=notrunc,fsync" "status=progress"
|
||||
ok "written"
|
||||
} else {
|
||||
say "Skipped."
|
||||
}
|
||||
}
|
||||
|
||||
step 8 "Next: add the module to your system flake"
|
||||
let uplink = ((do -i { ^ip route get 1.1.1.1 } | complete).stdout
|
||||
| parse -r '.* dev (?P<dev>\S+).*' | get dev | get 0? | default "eno1")
|
||||
|
||||
print $"
|
||||
(ansi dark_gray)# flake.nix(ansi reset)
|
||||
inputs.hermenix.url = \"path:(pwd)\";
|
||||
|
||||
(ansi dark_gray)# then in your modules list(ansi reset)
|
||||
hermenix.nixosModules.default
|
||||
|
||||
(ansi dark_gray)# configuration.nix(ansi reset)
|
||||
services.hermenix = \{
|
||||
enable = true;
|
||||
disk.baseDir = \"($base)\";
|
||||
network.externalInterface = \"($uplink)\";
|
||||
vcpu = 4;
|
||||
mem = 8192;
|
||||
\};
|
||||
"
|
||||
note $"detected uplink: ($uplink) — check that's right before rebuilding"
|
||||
|
||||
print $"
|
||||
Then:
|
||||
|
||||
sudo nixos-rebuild switch
|
||||
hermes-vm console (ansi dark_gray)# watch it boot(ansi reset)
|
||||
hermes-vm ssh (ansi dark_gray)# get in(ansi reset)
|
||||
|
||||
Inside the guest, in this order:
|
||||
|
||||
lsblk -f (ansi dark_gray)# CHECK LABELS match guest/hardware.nix(ansi reset)
|
||||
determinate-nixd login (ansi dark_gray)# FlakeHub Cache(ansi reset)
|
||||
sudo nix flake lock /etc/nixos
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
hermes setup
|
||||
hermes gateway install
|
||||
|
||||
Back on the host:
|
||||
|
||||
hermes-ctl units (ansi dark_gray)# confirm the gateway unit name(ansi reset)
|
||||
hermes-ctl status
|
||||
hermes-ctl soul
|
||||
"
|
||||
|
||||
warn "Check the disk labels before the guest's first nixos-rebuild. If they"
|
||||
warn "don't match guest/hardware.nix, the first self-rebuild produces a"
|
||||
warn "system that won't boot."
|
||||
|
||||
print $"\n(ansi green)✓ host setup complete(ansi reset)\n"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- migrate ---
|
||||
|
||||
# Carry an existing flat HERMES_HOME (e.g. the nousresearch/hermes-agent
|
||||
# Docker image, HERMES_HOME bind-mounted from the host) into a hermenix
|
||||
# guest, preserving its exact layout.
|
||||
#
|
||||
# SAFETY: only ever reads from `source`. Nothing there is deleted or moved —
|
||||
# the original stays a fully intact fallback. If anything goes wrong after
|
||||
# this, `sudo nixos-rebuild switch --rollback` on the host restores the
|
||||
# previous deployment pointed at the same, untouched source data.
|
||||
#
|
||||
# Run this AFTER setup + the host's nixos-rebuild have brought the guest up
|
||||
# at least once (so the state disk is formatted and mounted), and
|
||||
# `hermes-vm ssh true` succeeds.
|
||||
def "main migrate" [
|
||||
source: string # existing flat HERMES_HOME to copy from (read-only)
|
||||
--vsock-cid: int = 77 # must match services.hermenix.vsockCid on the host
|
||||
--guest-user: string = "hermes"
|
||||
--dest: string = "/var/lib/hermes" # where it lands in the guest; match services.hermenix.hermesHome
|
||||
--rewrite-from: list<string> = [host.docker.internal fwdesk.lab.internal castle.hub.internal]
|
||||
--rewrite-to: list<string> = [10.77.0.1 10.77.0.1 10.0.12.1]
|
||||
--rewrite-files: list<string> = [config.yaml auth.json context_length_cache.yaml .env]
|
||||
] {
|
||||
if not ($source | path exists) { die $"($source) is not a directory" }
|
||||
if ($rewrite_from | length) != ($rewrite_to | length) {
|
||||
die "--rewrite-from and --rewrite-to must have the same length"
|
||||
}
|
||||
|
||||
let ssh_base = [
|
||||
"ssh"
|
||||
"-o" $"ProxyCommand=socat - VSOCK-CONNECT:($vsock_cid):22"
|
||||
"-o" "StrictHostKeyChecking=accept-new"
|
||||
$"($guest_user)@hermes"
|
||||
]
|
||||
def gssh [...args: string] {
|
||||
let full = $ssh_base ++ $args
|
||||
^($full | first) ...($full | skip 1)
|
||||
}
|
||||
|
||||
say $"Source \(read-only\): ($source)"
|
||||
say $"Destination \(guest\): ($guest_user)@hermes:($dest) \(over vsock, cid ($vsock_cid)\)"
|
||||
print ""
|
||||
say "This will:"
|
||||
say $" 1. tar '($source)' \(not modifying it\) and stream it into the guest"
|
||||
say " 2. rewrite these hostnames in the migrated config, in the guest only:"
|
||||
for i in 0..(($rewrite_from | length) - 1) {
|
||||
say $" ($rewrite_from | get $i) -> ($rewrite_to | get $i)"
|
||||
}
|
||||
print ""
|
||||
if not (confirm-word "migrate" "Type 'migrate' to proceed:") { die "aborted" }
|
||||
|
||||
step 1 "confirming guest is reachable"
|
||||
gssh "true"
|
||||
|
||||
step 2 $"streaming ($source) -> guest:($dest) \(this can take a while for 8G+\)"
|
||||
let stream_argv = $ssh_base ++ [$"mkdir -p '($dest)' && tar -C '($dest)' -xf -"]
|
||||
^tar -C $source -cf - . | ^($stream_argv | first) ...($stream_argv | skip 1)
|
||||
|
||||
step 3 "rewriting stale hostnames in the guest"
|
||||
let sed_expr = (0..(($rewrite_from | length) - 1)
|
||||
| each {|i| $"s#($rewrite_from | get $i)#($rewrite_to | get $i)#g" }
|
||||
| str join "; ")
|
||||
for f in $rewrite_files {
|
||||
let path = $"($dest)/($f)"
|
||||
gssh $"[ -f '($path)' ] && sed -i '($sed_expr)' '($path)' && echo ' rewrote ($f)' || echo ' ($f) not present, skipping'"
|
||||
}
|
||||
|
||||
print ""
|
||||
ok $"Done. The original at ($source) is untouched."
|
||||
print ""
|
||||
say "Next, inside the guest (hermes-vm ssh):"
|
||||
say $" export HERMES_HOME=($dest)"
|
||||
say " # then the usual install steps from README.md:"
|
||||
say " # determinate-nixd login"
|
||||
say " # sudo nix flake lock /etc/nixos"
|
||||
say " # curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash"
|
||||
say " # hermes setup"
|
||||
say " # hermes gateway install"
|
||||
print ""
|
||||
say "Then verify with hermes-ctl status / logs before considering the old"
|
||||
say "deployment retired. Decrypt secrets/hermes-env.age yourself and fold"
|
||||
say $"anything relevant into ($dest)/.env \(hermes-ctl secrets edit\)."
|
||||
}
|
||||
@@ -1,380 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# hermes-vm guided setup.
|
||||
#
|
||||
# Walks the steps that have to happen before `nixos-rebuild switch`:
|
||||
# the disk images, the cache signing key, filling in guest/common.nix, building the
|
||||
# bootstrap image and writing it to disk.
|
||||
#
|
||||
# Safe to re-run. Every step checks whether it is already done and offers to
|
||||
# skip. Nothing is destructive without an explicit confirmation.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# ---------------------------------------------------------------- output ---
|
||||
|
||||
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
|
||||
B=$'\033[1m'; DIM=$'\033[2m'; R=$'\033[31m'; Y=$'\033[33m'; G=$'\033[32m'; N=$'\033[0m'
|
||||
else
|
||||
B=""; DIM=""; R=""; Y=""; G=""; N=""
|
||||
fi
|
||||
|
||||
step_n=0
|
||||
step() { step_n=$((step_n + 1)); printf '\n%s== %d. %s%s\n' "$B" "$step_n" "$*" "$N"; }
|
||||
say() { printf ' %s\n' "$*"; }
|
||||
note() { printf ' %s%s%s\n' "$DIM" "$*" "$N"; }
|
||||
ok() { printf ' %s✓%s %s\n' "$G" "$N" "$*"; }
|
||||
warn() { printf ' %s!%s %s\n' "$Y" "$N" "$*"; }
|
||||
die() { printf '\n%serror:%s %s\n' "$R" "$N" "$*" >&2; exit 1; }
|
||||
|
||||
ask() { # ask VAR "prompt" "default"
|
||||
local __var="$1" __prompt="$2" __default="${3:-}" __reply
|
||||
if [ -n "$__default" ]; then
|
||||
read -r -p " $__prompt [$__default]: " __reply || true
|
||||
__reply="${__reply:-$__default}"
|
||||
else
|
||||
read -r -p " $__prompt: " __reply || true
|
||||
fi
|
||||
printf -v "$__var" '%s' "$__reply"
|
||||
}
|
||||
|
||||
confirm() { # confirm "prompt" -> 0 if yes
|
||||
local reply
|
||||
read -r -p " $1 [y/N] " reply || true
|
||||
case "$reply" in [yY]*) return 0 ;; *) return 1 ;; esac
|
||||
}
|
||||
|
||||
confirm_word() { # confirm_word "word" "prompt" -> 0 if they typed the word
|
||||
local reply
|
||||
read -r -p " $2 " reply || true
|
||||
[ "$reply" = "$1" ]
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------ setup ---
|
||||
|
||||
cd "$(dirname "$(readlink -f "$0")")"
|
||||
|
||||
if [ "$(id -u)" -eq 0 ]; then
|
||||
SUDO=""
|
||||
else
|
||||
command -v sudo >/dev/null || die "not root and sudo is not available"
|
||||
SUDO="sudo"
|
||||
fi
|
||||
|
||||
COMMON="guest/common.nix"
|
||||
CACHE_NAME="hermes-cache-1"
|
||||
SECRET_KEY="/var/lib/secrets/hermes-cache.secret"
|
||||
PUBLIC_KEY="/var/lib/secrets/hermes-cache.pub"
|
||||
DETERMINATE_SUB="https://install.determinate.systems"
|
||||
DETERMINATE_KEY="cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM="
|
||||
|
||||
printf '%s\n' "$B"
|
||||
cat <<'BANNER'
|
||||
hermes-vm · guided setup
|
||||
BANNER
|
||||
printf '%s' "$N"
|
||||
note "This prepares the host. It does not run nixos-rebuild — you'll paste a"
|
||||
note "module snippet into your own configuration at the end."
|
||||
|
||||
# ------------------------------------------------------------- preflight ---
|
||||
|
||||
step "Checking prerequisites"
|
||||
|
||||
[ -f flake.nix ] && [ -f "$COMMON" ] \
|
||||
|| die "run this from the hermes-vm repository root"
|
||||
|
||||
command -v nix >/dev/null || die "nix not found on PATH"
|
||||
nix flake --help >/dev/null 2>&1 \
|
||||
|| die "flakes are not enabled. Add 'experimental-features = nix-command flakes' to /etc/nix/nix.conf"
|
||||
ok "nix with flakes"
|
||||
|
||||
command -v btrfs >/dev/null || die "btrfs-progs not found. Snapshots need it."
|
||||
command -v mkfs.ext4 >/dev/null || die "mkfs.ext4 not found (e2fsprogs)"
|
||||
ok "btrfs-progs"
|
||||
|
||||
[ -e /dev/kvm ] || die "/dev/kvm is missing. KVM is required; check virtualisation is enabled in firmware."
|
||||
ok "kvm"
|
||||
|
||||
if command -v nixos-version >/dev/null; then
|
||||
ok "host is NixOS ($(nixos-version | cut -d' ' -f1))"
|
||||
else
|
||||
warn "this host does not look like NixOS — the module expects NixOS"
|
||||
fi
|
||||
|
||||
# ----------------------------------------------------------------- disks ---
|
||||
|
||||
step "Guest disks"
|
||||
|
||||
note "Two disks, deliberately:"
|
||||
note " system - NixOS and the Nix store. Big, churny, rebuildable. Not backed up."
|
||||
note " state - identity, memories, workspace, /etc/nixos. Small. Snapshotted."
|
||||
|
||||
ask BASE "Directory for the disk images" "/var/lib/hermes-vm"
|
||||
|
||||
FSTYPE="$(stat -f -c %T "$(dirname "$BASE")" 2>/dev/null || echo unknown)"
|
||||
if [ "$FSTYPE" != "btrfs" ]; then
|
||||
warn "$(dirname "$BASE") is $FSTYPE, not btrfs"
|
||||
warn "snapshots need btrfs. Everything else works; you'd rely on backups alone."
|
||||
confirm "Continue anyway?" || die "aborted"
|
||||
USE_BTRFS=no
|
||||
else
|
||||
USE_BTRFS=yes
|
||||
fi
|
||||
|
||||
$SUDO mkdir -p "$BASE"
|
||||
|
||||
make_subvol() { # make_subvol path
|
||||
if [ "$USE_BTRFS" = yes ] && ! $SUDO btrfs subvolume show "$1" >/dev/null 2>&1; then
|
||||
$SUDO rmdir "$1" 2>/dev/null || true
|
||||
$SUDO btrfs subvolume create "$1" >/dev/null
|
||||
# nodatacow BEFORE any file exists in here. Btrfs is copy-on-write and so
|
||||
# is a VM writing to a disk image; stacked, the image fragments badly.
|
||||
# Only applies to files created afterwards, hence the ordering.
|
||||
$SUDO chattr +C "$1"
|
||||
$SUDO btrfs property set "$1" compression none 2>/dev/null || true
|
||||
ok "subvolume $1 (nodatacow)"
|
||||
else
|
||||
$SUDO mkdir -p "$1"
|
||||
fi
|
||||
}
|
||||
|
||||
make_subvol "$BASE/system"
|
||||
make_subvol "$BASE/state"
|
||||
$SUDO mkdir -p "$BASE/snapshots"
|
||||
|
||||
SYSTEM_IMG="$BASE/system/system.raw"
|
||||
STATE_IMG="$BASE/state/state.raw"
|
||||
|
||||
# --- system disk ---
|
||||
if $SUDO test -f "$SYSTEM_IMG"; then
|
||||
ok "system disk exists ($($SUDO du -h --apparent-size "$SYSTEM_IMG" | cut -f1))"
|
||||
SYSTEM_EXISTED=yes
|
||||
else
|
||||
SYSTEM_EXISTED=no
|
||||
ask SYSSIZE "System disk size" "80G"
|
||||
$SUDO truncate -s "$SYSSIZE" "$SYSTEM_IMG"
|
||||
if [ "$USE_BTRFS" = yes ]; then
|
||||
$SUDO lsattr -l "$SYSTEM_IMG" 2>/dev/null | grep -q "No_COW" \
|
||||
&& ok "system disk created, nodatacow confirmed" \
|
||||
|| warn "system disk created but nodatacow did NOT apply - check 'lsattr $SYSTEM_IMG'"
|
||||
else
|
||||
ok "system disk created"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- state disk ---
|
||||
if $SUDO test -f "$STATE_IMG"; then
|
||||
ok "state disk exists ($($SUDO du -h --apparent-size "$STATE_IMG" | cut -f1))"
|
||||
else
|
||||
ask STATESIZE "State disk size" "20G"
|
||||
$SUDO truncate -s "$STATESIZE" "$STATE_IMG"
|
||||
$SUDO mkfs.ext4 -q -L hermes-state "$STATE_IMG"
|
||||
ok "state disk created and formatted (label: hermes-state)"
|
||||
fi
|
||||
|
||||
# ------------------------------------------------------------- cache key ---
|
||||
|
||||
step "Binary cache signing key"
|
||||
|
||||
note "The host serves its store to the guest read-only, so the guest doesn't"
|
||||
note "re-download from the internet what you already have."
|
||||
|
||||
if $SUDO test -f "$SECRET_KEY"; then
|
||||
ok "signing key already exists"
|
||||
else
|
||||
$SUDO mkdir -p /var/lib/secrets
|
||||
$SUDO nix-store --generate-binary-cache-key "$CACHE_NAME" "$SECRET_KEY" "$PUBLIC_KEY"
|
||||
$SUDO chmod 0400 "$SECRET_KEY"
|
||||
ok "generated $CACHE_NAME"
|
||||
fi
|
||||
|
||||
CACHE_PUB="$($SUDO cat "$PUBLIC_KEY")"
|
||||
say "Public key: ${DIM}${CACHE_PUB}${N}"
|
||||
|
||||
# nix-serve's user only exists once the module has been applied, so this is
|
||||
# expected to fail on a first run.
|
||||
if id nix-serve >/dev/null 2>&1; then
|
||||
$SUDO chown nix-serve "$SECRET_KEY"
|
||||
ok "key owned by nix-serve"
|
||||
else
|
||||
warn "the nix-serve user does not exist yet — that's normal on a first run"
|
||||
note "after your nixos-rebuild, run:"
|
||||
note " sudo chown nix-serve $SECRET_KEY"
|
||||
fi
|
||||
|
||||
# ------------------------------------------------------------- ssh keys ----
|
||||
|
||||
step "SSH access to the guest"
|
||||
|
||||
CURRENT_KEYS="$(sed -n '/^ authorizedKeys = \[/,/^ \];/p' "$COMMON" | grep -c '^\s*"ssh-' || true)"
|
||||
if [ "${CURRENT_KEYS:-0}" -gt 0 ]; then
|
||||
ok "$CURRENT_KEYS key(s) already configured in $COMMON"
|
||||
if confirm "Replace them?"; then CURRENT_KEYS=0; fi
|
||||
fi
|
||||
|
||||
SELECTED_KEYS=""
|
||||
if [ "${CURRENT_KEYS:-0}" -eq 0 ]; then
|
||||
mapfile -t FOUND < <(ls -1 "$HOME"/.ssh/*.pub 2>/dev/null || true)
|
||||
if [ "${#FOUND[@]}" -gt 0 ]; then
|
||||
say "Public keys found in ~/.ssh:"
|
||||
i=0
|
||||
for f in "${FOUND[@]}"; do
|
||||
i=$((i + 1))
|
||||
note " $i) $(basename "$f") — $(cut -d' ' -f3- "$f")"
|
||||
done
|
||||
ask PICK "Numbers to use (space separated, or 'n' to paste one)" "1"
|
||||
if [ "$PICK" != "n" ]; then
|
||||
for n in $PICK; do
|
||||
f="${FOUND[$((n - 1))]:-}"
|
||||
[ -n "$f" ] || die "no such option: $n"
|
||||
SELECTED_KEYS+=" \"$(tr -d '\n' < "$f")\"
|
||||
"
|
||||
done
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ -z "$SELECTED_KEYS" ]; then
|
||||
ask PASTED "Paste a public key (blank to skip)"
|
||||
[ -n "$PASTED" ] && SELECTED_KEYS=" \"$PASTED\"
|
||||
"
|
||||
fi
|
||||
|
||||
if [ -z "$SELECTED_KEYS" ]; then
|
||||
warn "no SSH key set — you'll only be able to reach the guest with 'hermes-vm console'"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ------------------------------------------------------ patch common.nix ---
|
||||
|
||||
step "Writing $COMMON"
|
||||
|
||||
[ -f "$COMMON.bak" ] || cp "$COMMON" "$COMMON.bak"
|
||||
note "original saved as $COMMON.bak"
|
||||
|
||||
# cachePublicKey
|
||||
tmp="$(mktemp)"
|
||||
sed 's|^\( cachePublicKey = \).*|\1"'"$CACHE_PUB"'";|' "$COMMON" > "$tmp"
|
||||
mv "$tmp" "$COMMON"
|
||||
ok "cachePublicKey set"
|
||||
|
||||
# authorizedKeys block
|
||||
if [ -n "$SELECTED_KEYS" ]; then
|
||||
tmp="$(mktemp)"
|
||||
awk -v keys="$SELECTED_KEYS" '
|
||||
/^ authorizedKeys = \[/ { print; printf "%s", keys; inblock = 1; next }
|
||||
inblock && /^ \];/ { inblock = 0; print; next }
|
||||
inblock { next }
|
||||
{ print }
|
||||
' "$COMMON" > "$tmp"
|
||||
mv "$tmp" "$COMMON"
|
||||
ok "authorizedKeys set ($(printf '%s' "$SELECTED_KEYS" | grep -c '^' ) key(s))"
|
||||
fi
|
||||
|
||||
# ----------------------------------------------------------- build image ---
|
||||
|
||||
step "Building the bootstrap image"
|
||||
|
||||
note "The extra substituter flags stop you compiling Determinate Nix yourself."
|
||||
|
||||
if confirm "Build now? (first run can take a while)"; then
|
||||
nix build .#hermes-guest-image \
|
||||
--option extra-substituters "$DETERMINATE_SUB" \
|
||||
--option extra-trusted-public-keys "$DETERMINATE_KEY"
|
||||
ok "built"
|
||||
else
|
||||
say "Skipped. Run manually:"
|
||||
note " nix build .#hermes-guest-image \\"
|
||||
note " --option extra-substituters $DETERMINATE_SUB \\"
|
||||
note " --option extra-trusted-public-keys $DETERMINATE_KEY"
|
||||
fi
|
||||
|
||||
# ------------------------------------------------------------ write disk ---
|
||||
|
||||
step "Writing the bootstrap image to the system disk"
|
||||
|
||||
IMAGE="$(ls -1 result/*.img 2>/dev/null | head -n1 || true)"
|
||||
|
||||
if [ -z "$IMAGE" ]; then
|
||||
warn "no image found under ./result - skipping"
|
||||
note "build it, then:"
|
||||
note " sudo dd if=result/nixos.img of=$SYSTEM_IMG bs=4M conv=notrunc,fsync status=progress"
|
||||
else
|
||||
IMG_BYTES=$(stat -Lc %s "$IMAGE")
|
||||
VOL_BYTES=$($SUDO stat -c %s "$SYSTEM_IMG")
|
||||
say "image: $IMAGE ($((IMG_BYTES / 1024 / 1024)) MiB)"
|
||||
say "target: $SYSTEM_IMG ($((VOL_BYTES / 1024 / 1024 / 1024)) GiB)"
|
||||
[ "$IMG_BYTES" -le "$VOL_BYTES" ] || die "image is larger than the system disk"
|
||||
|
||||
if [ "$SYSTEM_EXISTED" = yes ]; then
|
||||
warn "the system disk already existed. Writing the image replaces the"
|
||||
warn "guest OS. Hermes's identity and memories live on the STATE disk and"
|
||||
warn "are untouched, but anything it installed outside /var/lib/hermes is lost."
|
||||
fi
|
||||
|
||||
if confirm_word "overwrite" "Type 'overwrite' to write the image:"; then
|
||||
# notrunc so the file keeps its full size; the image is smaller than the disk
|
||||
$SUDO dd if="$IMAGE" of="$SYSTEM_IMG" bs=4M conv=notrunc,fsync status=progress
|
||||
ok "written"
|
||||
else
|
||||
say "Skipped."
|
||||
fi
|
||||
fi
|
||||
|
||||
# ----------------------------------------------------------- next steps ----
|
||||
|
||||
UPLINK="$(ip route get 1.1.1.1 2>/dev/null | sed -n 's/.* dev \([^ ]*\).*/\1/p' | head -n1)"
|
||||
UPLINK="${UPLINK:-eno1}"
|
||||
|
||||
step "Next: add the module to your system flake"
|
||||
|
||||
cat <<EOF
|
||||
|
||||
${DIM}# flake.nix${N}
|
||||
inputs.hermes-vm.url = "path:$(pwd)";
|
||||
|
||||
${DIM}# then in your modules list${N}
|
||||
hermes-vm.nixosModules.default
|
||||
|
||||
${DIM}# configuration.nix${N}
|
||||
services.hermesVm = {
|
||||
enable = true;
|
||||
disk.baseDir = "$BASE";
|
||||
network.externalInterface = "$UPLINK";
|
||||
vcpu = 4;
|
||||
mem = 8192;
|
||||
};
|
||||
|
||||
EOF
|
||||
|
||||
note "detected uplink: $UPLINK — check that's right before rebuilding"
|
||||
|
||||
cat <<EOF
|
||||
|
||||
Then:
|
||||
|
||||
sudo nixos-rebuild switch
|
||||
hermes-vm console ${DIM}# watch it boot${N}
|
||||
hermes-vm ssh ${DIM}# get in${N}
|
||||
|
||||
Inside the guest, in this order:
|
||||
|
||||
lsblk -f ${DIM}# CHECK LABELS match guest/hardware.nix${N}
|
||||
determinate-nixd login ${DIM}# FlakeHub Cache${N}
|
||||
sudo nix flake lock /etc/nixos
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
hermes setup
|
||||
hermes gateway install
|
||||
|
||||
Back on the host:
|
||||
|
||||
hermes-ctl units ${DIM}# confirm the gateway unit name${N}
|
||||
hermes-ctl status
|
||||
hermes-ctl soul
|
||||
|
||||
EOF
|
||||
|
||||
warn "Check the disk labels before the guest's first nixos-rebuild. If they"
|
||||
warn "don't match guest/hardware.nix, the first self-rebuild produces a"
|
||||
warn "system that won't boot."
|
||||
|
||||
printf '\n%s✓ host setup complete%s\n\n' "$G" "$N"
|
||||
Reference in new issue
Block a user