Files
hermenix/nu/hermenix.nu
T
ariandClaude Sonnet 5 c39be5e6de Fix deprecated 'str downcase' in confirm helper
str downcase/str lowercase differ across nu versions (renamed in
0.114.0); avoid depending on either by checking both cases directly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-15 14:17:18 -04:00

491 lines
19 KiB
Nu

#!/usr/bin/env nu
#
# hermenix — host-side tooling for the Hermes Agent VM.
#
# Three 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
# hermenix remote <host> ... run either of the above ON a remote host over
# SSH, instead of having to SSH in yourself first
#
# None of these run `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 starts-with "y") or ($reply | str starts-with "Y"))
}
def confirm-word [word: string, prompt: string] {
(input $" ($prompt) ") == $word
}
# Single-quote a string for safe embedding in a remote shell command line.
def shquote [s: string] {
"'" + ($s | str replace --all "'" "'\\''") + "'"
}
# 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 " hermenix remote <host> ... run setup/migrate on a remote host over SSH"
print ""
print "run `hermenix <subcommand> --help` for details on any of these."
}
# ------------------------------------------------------------------ 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\)."
}
# ----------------------------------------------------------------- remote ---
# Run `hermenix setup` or `hermenix migrate` on a remote host over SSH,
# instead of having to SSH in and run it locally yourself. `setup` and
# `migrate` both act on whatever machine they run on (local disks, local
# sudo, vsock into the local guest) - this just saves the manual SSH step.
#
# Clones `--repo` to `--dir` on the remote ONLY if `--dir` doesn't already
# exist there - an existing checkout is never touched beyond running the
# command, so a host's own guest/common.nix edits (cache key, authorized
# keys) or in-progress disk state are never at risk of being overwritten.
def "main remote" [
host: string # SSH target, e.g. fwdesk.lab.internal
...args: string # forwarded to the remote `hermenix` invocation
--dir: string = "hermenix" # checkout path on the remote, relative to $HOME
--repo: string = "ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
] {
if ($args | is-empty) {
die "usage: hermenix remote <host> <setup|migrate> [args...]"
}
let quoted_args = ($args | each {|a| shquote $a } | str join " ")
let remote_cmd = $"if [ ! -d (shquote $dir) ]; then git clone (shquote $repo) (shquote $dir); fi && cd (shquote $dir) && nix run .#hermenix -- ($quoted_args)"
say $"Running on ($host): ($args | str join ' ')"
^ssh -t -o StrictHostKeyChecking=accept-new $host $remote_cmd
}