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

+3 -3
View File
@@ -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
View File
@@ -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
```
+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`.
+41 -20
View File
@@ -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
View File
@@ -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.
-111
View File
@@ -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
View File
@@ -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
View File
@@ -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\)."
}
-380
View File
@@ -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"