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
+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\)."
|
||||
}
|
||||
Reference in new issue
Block a user