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>
454 lines
18 KiB
Nu
454 lines
18 KiB
Nu
#!/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\)."
|
|
}
|