new single file with fixes

This commit is contained in:
ari committed 2026-09-17 12:15:53 -04:00
1 parent f5f6a98152
commit 21e87b6bfa
10 files changed
+710 -778

No files matched your search

+14 -44
View File
@@ -15,7 +15,16 @@
let
system = "x86_64-linux";
pkgs = nixpkgs.legacyPackages.${system};
nuScript = path: (builtins.readFile ./nu/lib/common.nu) + "\n" + (builtins.readFile path);
nuScript = builtins.concatStringsSep "\n" (map builtins.readFile [
./nu/lib/common.nu
./nu/lib/guest.nu
./nu/host/setup.nu
./nu/host/migrate.nu
./nu/host/remote.nu
./nu/vm/vm.nu
./nu/ctl/ctl.nu
./nu/hermenix.nu
]);
gitRev = self.rev or self.dirtyRev or "unknown";
shortRev = if gitRev == "unknown" then "unknown" else builtins.substring 0 7 gitRev;
version =
@@ -51,7 +60,10 @@
gnused
btrfs-progs
e2fsprogs
util-linux
restic
coreutils
vim
nix
]))
"--set"
@@ -59,49 +71,7 @@
version
];
}
(nuScript ./nu/hermenix.nu);
hermes-vm = pkgs.writers.writeNuBin "hermes-vm"
{
makeWrapperArgs = [
"--prefix"
"PATH"
":"
(pkgs.lib.makeBinPath (with pkgs; [
openssh
socat
coreutils
gnutar
btrfs-progs
util-linux
restic
]))
"--set"
"HERMENIX_VERSION"
version
];
}
(nuScript ./nu/hermes-vm.nu);
hermes-ctl = pkgs.writers.writeNuBin "hermes-ctl"
{
makeWrapperArgs = [
"--prefix"
"PATH"
":"
(pkgs.lib.makeBinPath (with pkgs; [
openssh
socat
coreutils
gnutar
vim
]))
"--set"
"HERMENIX_VERSION"
version
];
}
(nuScript ./nu/hermes-ctl.nu);
nuScript;
default = self.packages.${system}.hermenix;
};
+20 -52
View File
@@ -341,22 +341,12 @@ in
};
};
cliName = mkOption {
type = types.str;
default = "hermes-ctl";
description = ''
Name of the host-side wrapper that drives Hermes inside the guest.
Set to "hermes" if you want it to feel local and are sure nothing
else on the host claims that name.
'';
};
gatewayUnit = mkOption {
type = types.str;
default = "hermes-agent";
description = ''
The systemd *user* unit that `hermes gateway install` created in the
guest. Check with `hermes-ctl units` after installing; upstream has
guest. Check with `hermenix ctl units` after installing; upstream has
used more than one name for this.
'';
};
@@ -372,7 +362,7 @@ in
deployment) that you're placing directly at the root of the state
disk instead of under .hermes - see `hermenix migrate --help`.
This only changes where the host-side hermes-ctl wrapper (soul,
This only changes where the host-side `hermenix ctl` commands (soul,
memory, conf, secrets, reseed, pull) looks. It does not change what
the gateway process itself uses - export HERMES_HOME to match inside
the guest when you install it.
@@ -389,7 +379,7 @@ in
type = types.str;
default = "dev";
description = ''
"YYYY.MM.DD-<commit-sha>" reported by hermes-vm/hermes-ctl's
"YYYY.MM.DD-<commit-sha>" reported by `hermenix version`.
`version` subcommand. Normally supplied for free by this flake's own
`nixosModules.default` (from its git metadata) - the "dev" default
here only shows up if this module is imported some other way.
@@ -819,12 +809,10 @@ in
};
environment.systemPackages = [
# Nu scripts, shared with the standalone flake packages of the same
# name (packages.hermes-vm / packages.hermes-ctl) - see flake.nix. The
# per-host values that used to be spliced into the bash strings here
# via Nix interpolation are passed in as env vars instead, via
# makeWrapperArgs' --set, same mechanism already used for PATH below.
(pkgs.writers.writeNuBin "hermes-vm"
# Single consolidated CLI: `hermenix vm *` controls the VM,
# `hermenix ctl *` drives Hermes inside it. Per-host values are
# passed as env vars via makeWrapperArgs --set.
(pkgs.writers.writeNuBin "hermenix"
{
makeWrapperArgs = [
"--prefix"
@@ -835,9 +823,12 @@ in
socat
coreutils
gnutar
gnused
btrfs-progs
util-linux
restic
vim
nix
]))
"--set"
"HERMES_VSOCK_CID"
@@ -849,49 +840,26 @@ in
"HERMES_DISK_BASE_DIR"
cfg.disk.baseDir
"--set"
"HERMENIX_VERSION"
cfg.version
];
}
((builtins.readFile ../nu/lib/common.nu) + "\n" + (builtins.readFile ../nu/hermes-vm.nu)))
# ---------------------------------------------------------------
# Driving Hermes itself, as opposed to the VM around it.
# ---------------------------------------------------------------
(pkgs.writers.writeNuBin cfg.cliName
{
makeWrapperArgs = [
"--prefix"
"PATH"
":"
(lib.makeBinPath (with pkgs; [
openssh
socat
coreutils
gnutar
vim
]))
"--set"
"HERMES_VSOCK_CID"
(toString cfg.vsockCid)
"--set"
"HERMES_GUEST_NAME"
cfg.name
"--set"
"HERMES_HOME_DIR"
cfg.hermesHome
"--set"
"HERMES_GATEWAY_UNIT"
cfg.gatewayUnit
"--set"
"HERMES_CLI_NAME"
cfg.cliName
"--set"
"HERMENIX_VERSION"
cfg.version
];
}
((builtins.readFile ../nu/lib/common.nu) + "\n" + (builtins.readFile ../nu/hermes-ctl.nu)))
(builtins.concatStringsSep "\n" (map builtins.readFile [
../nu/lib/common.nu
../nu/lib/guest.nu
../nu/host/setup.nu
../nu/host/migrate.nu
../nu/host/remote.nu
../nu/vm/vm.nu
../nu/ctl/ctl.nu
../nu/hermenix.nu
])))
];
};
}
+127
View File
@@ -0,0 +1,127 @@
# hermenix ctl — drive Hermes inside the guest.
#
# Identity, config, secrets, gateway service, and a passthrough to the
# hermes CLI itself. For controlling the VM around it, see vm/vm.nu.
#
# Depends on: lib/common.nu, lib/guest.nu (ssh-args).
def home-dir [] { $env.HERMES_HOME_DIR? | default "/var/lib/hermes-vm/.hermes" }
def gateway-unit [] { $env.HERMES_GATEWAY_UNIT? | default "hermes-agent" }
def ctl-gssh [cmd: string] { run-argv ((ssh-args) ++ [$cmd]) }
# Pull a file out of the guest, open it in $EDITOR, push it back.
# Skips the write if nothing changed (hash comparison).
def edit-remote [remote: string, mode: string = "0644"] {
let tmp = (mktemp)
let fetched = (do -i { ctl-gssh $"cat ($remote)" } | complete)
$fetched.stdout | save -f $tmp
let before = (open --raw $tmp | hash sha256)
^($env.EDITOR? | default "vim") $tmp
if (open --raw $tmp | hash sha256) == $before {
rm $tmp
say "unchanged"
return
}
(open --raw $tmp) | ctl-gssh $"install -m ($mode) /dev/stdin ($remote)"
rm $tmp
say $"written to ($remote)"
if (confirm "restart the gateway now?") {
ctl-gssh $"systemctl --user restart (gateway-unit)"
}
}
# Everything not matched by a more-specific `main ctl *` goes straight to the
# hermes CLI in the guest, with a pty for interactive subcommands like `chat`.
#
# A single string, not rest args: nu's parser tries to match any bare
# --flag-shaped token against this command's own flags before it ever
# reaches a rest parameter, so `hermenix ctl chat --model x` would fail to
# parse. Quote the whole thing instead — e.g. `hermenix ctl "chat --model x"`.
def "main ctl" [remainder: string = ""] {
if $remainder == "" {
print "usage: hermenix ctl <subcommand>"
print ""
print " soul [edit] show or edit SOUL.md"
print " memory [edit] show or edit memories/USER.md"
print " conf [edit] show or edit config.yaml"
print " secrets [edit|show] manage .env (keys masked by default)"
print " status gateway service status"
print " logs follow gateway journal (-f)"
print " restart restart the gateway"
print " units list all hermes* user units"
print " reseed overwrite identity from /etc/nixos/hermes"
print " pull [dir] copy live identity back to the host"
print ""
print "Anything else is passed straight to the hermes CLI in the guest:"
print " hermenix ctl \"chat\""
print " hermenix ctl \"update\""
print " hermenix ctl \"sessions list\""
exit 1
}
let words = ($remainder | split row " " | where {|w| $w != "" })
run-argv ((ssh-args) ++ ["-t" "hermes"] ++ $words)
}
def "main ctl soul" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/SOUL.md"
} else {
ctl-gssh $"cat (home-dir)/SOUL.md"
}
}
def "main ctl memory" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/memories/USER.md"
} else {
ctl-gssh $"cat (home-dir)/memories/USER.md"
}
}
def "main ctl conf" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/config.yaml"
} else {
ctl-gssh $"cat (home-dir)/config.yaml"
}
}
# API keys. Mode 0600, never enters the Nix store, and not printed unless
# you ask for it explicitly.
def "main ctl secrets" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/.env" "0600"
} else if $action == "show" {
ctl-gssh $"cat (home-dir)/.env"
} else {
ctl-gssh $"sed 's/=.*/=<set>/' (home-dir)/.env"
}
}
def "main ctl status" [] { ctl-gssh $"systemctl --user status (gateway-unit) --no-pager" }
def "main ctl logs" [] { run-argv ((ssh-args) ++ ["-t" $"journalctl --user -u (gateway-unit) -f"]) }
def "main ctl restart" [] { ctl-gssh $"systemctl --user restart (gateway-unit)" }
def "main ctl units" [] { ctl-gssh "systemctl --user list-units 'hermes*' --all --no-pager" }
# Overwrite the agent's identity from the seed. Destructive — this is how
# you undo whatever it has decided about itself.
def "main ctl reseed" [] {
warn "This overwrites SOUL.md, memories and config.yaml in the guest"
warn "with the seed from /etc/nixos/hermes. Anything Hermes has"
warn "learned and written there is lost."
if not (confirm-word "reseed" "type 'reseed' to confirm:") { die "aborted" }
ctl-gssh $"cp -rT /etc/nixos/hermes/home (home-dir) && cp -rT /etc/nixos/hermes/workspace /var/lib/hermes/workspace && systemctl --user restart (gateway-unit)"
ok "reseeded"
}
# Copy the agent's live identity back here, so you can fold what it has
# learned into the seed in guest/hermes/.
def "main ctl pull" [dest: string = "./hermes-home"] {
mkdir $dest
(ctl-gssh $"tar -C (home-dir) --exclude=.env --exclude=sessions --exclude=state.db -cf - .") | ^tar -C $dest -xf -
say $"pulled to ($dest) (secrets and sessions excluded)"
}
+22 -490
View File
@@ -2,62 +2,28 @@
#
# hermenix — host-side tooling for the Hermes Agent VM.
#
# No local checkout needed for any of this. `hermenix` is a flake package,
# meant to be run straight from its git+ssh URL - `nix run <flake>#hermenix`
# (or install it once with `nix profile install <flake>#hermenix` / the
# nixos-setup overlay, then just `hermenix ...`). Host-specific settings
# (cache signing key, your SSH key) live at /etc/hermenix/local.nix on the
# host itself, not in a repo checkout - see guest/local.nix.example.
# No local checkout needed. `hermenix` is a flake package meant to be run
# straight from its git+ssh URL:
#
# Three subcommands:
# hermenix setup guided host-side setup: disks, cache signing
# key, /etc/hermenix/local.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> "<cmd>" run either of the above ON a remote host
# over SSH (quote <cmd> as one string, e.g.
# "setup --clean"), instead of having to SSH
# in yourself first
# nix run <flake>#hermenix
#
# None of these run `nixos-rebuild` — that stays yours to run, watching it
# happen.
# ---------------------------------------------------------------- output ---
# Or install once and just call it directly:
#
# say/note/ok/warn/die/step/ask/confirm/confirm-word/shquote/vsock-ssh-args/
# run-argv live in nu/lib/common.nu, shared with hermes-vm.nu and
# hermes-ctl.nu - see flake.nix, which concatenates it in front of this file.
# `truncate -s` treats a bare number as bytes, not gigabytes - the size
# prompts' own defaults ("80G", "20G") make gigabytes the obvious intent, so
# normalize a bare integer answer to that rather than silently creating a
# byte-sized disk. Anything with an existing suffix passes through as-is.
def normalize-size [s: string] {
try {
let n = ($s | into int)
$"($n)G"
} catch {
$s
}
}
# 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)
}
# nix profile install <flake>#hermenix (or via the nixos-setup overlay)
#
# Host-specific settings (cache signing key, SSH key) live at
# /etc/hermenix/local.nix — see guest/local.nix.example.
#
# Source layout (all concatenated by flake.nix in dependency order):
#
# lib/common.nu output helpers, run-argv, vsock-ssh-args
# lib/guest.nu shared guest-connection env helpers
# host/setup.nu hermenix setup
# host/migrate.nu hermenix migrate
# host/remote.nu hermenix remote
# vm/vm.nu hermenix vm *
# ctl/ctl.nu hermenix ctl *
# hermenix.nu this file — top-level dispatch (main)
def main [] {
print "usage: hermenix <subcommand> ..."
@@ -66,442 +32,8 @@ def main [] {
print " hermenix migrate <source> carry an existing flat HERMES_HOME into the guest"
print " hermenix remote <host> \"<cmd>\" 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, /etc/hermenix/local.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. Works
# from any directory - no local checkout of this repo needed.
def "main setup" [
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
--clean # stop the VM and delete existing disk images + UEFI vars first, for a fully fresh start
] {
$env.HERMENIX_NEED_SUDO = ((^id -u | str trim) != "0")
let local_path = "/etc/hermenix/local.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 (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"
if $clean {
warn "--clean: this stops the VM and deletes the existing system/state"
warn "disk images and UEFI vars under this directory. The btrfs"
warn "subvolumes and any snapshots are left alone."
if not (confirm-word "clean" "Type 'clean' to confirm:") { die "aborted" }
do -i { priv systemctl stop hermes-vm.service } | complete | ignore
do -i { priv rm "-f" $"($base)/system/system.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/state/state.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/OVMF_VARS.fd" } | complete | ignore
# A fresh state disk means a fresh SSH host key on next boot - drop the
# stale known_hosts entry now so the next connect doesn't fail on a
# host-key mismatch. Not run through priv: this is the invoking user's
# own ~/.ssh/known_hosts, not a root-owned path.
do -i { ^ssh-keygen -R hermes } | complete | ignore
ok "cleaned existing disk images and stale known_hosts entry"
}
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
priv chown "hermes-vm:hermes-vm" $path
ok $"subvolume ($path) \(nodatacow\)"
} else {
priv mkdir "-p" $path
priv chown "hermes-vm:hermes-vm" $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)
priv chown "hermes-vm:hermes-vm" $system_img
ok $"system disk exists \(($sz)\)"
} else {
let syssize = (normalize-size (ask "System disk size" "80G"))
priv truncate "-s" $syssize $system_img
priv chown "hermes-vm:hermes-vm" $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)
priv chown "hermes-vm:hermes-vm" $state_img
ok $"state disk exists \(($sz)\)"
} else {
let statesize = (normalize-size (ask "State disk size" "20G"))
priv truncate "-s" $statesize $state_img
priv mkfs.ext4 "-q" "-L" hermes-state $state_img
priv chown "hermes-vm:hermes-vm" $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 existing = if ($local_path | path exists) {
let evaluated = (do -i { ^nix-instantiate --eval --json --strict -E $"import ($local_path)" } | complete)
if $evaluated.exit_code == 0 {
$evaluated.stdout | from json
} else {
warn $"($local_path) exists but failed to evaluate - treating as empty"
{ cachePublicKey: "", authorizedKeys: [] }
}
} else {
{ cachePublicKey: "", authorizedKeys: [] }
}
let existing_keys = ($existing.authorizedKeys? | default [])
let replace_keys = if ($existing_keys | length) > 0 {
ok $"($existing_keys | length) key\(s\) already configured in ($local_path)"
confirm "Replace them?"
} else {
true
}
mut selected_keys = $existing_keys
if $replace_keys {
mut picked = []
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)"
}
$picked = ($picked | append (open ($found | get $idx) | str trim))
}
}
}
if ($picked | is-empty) {
let pasted = ask "Paste a public key (blank to skip)"
if $pasted != "" { $picked = [$pasted] }
}
if ($picked | is-empty) {
warn "no SSH key set — you'll only be able to reach the guest with 'hermes-vm console'"
}
$selected_keys = $picked
}
step 5 $"Writing ($local_path)"
let key_lines = ($selected_keys | each {|k| $" \"($k)\"" } | str join "\n")
let content = $"# Written by `hermenix setup`. Lives on the host, not in a repo checkout -
# see guest/local.nix.example in the hermenix repo for the reference shape.
\{
cachePublicKey = \"($cache_pub)\";
authorizedKeys = [
($key_lines)
];
\}
"
let tmp = (^mktemp | str trim)
$content | save -f $tmp
priv mkdir "-p" (($local_path | path dirname))
priv cp $tmp $local_path
priv chmod 0644 $local_path
rm $tmp
ok $"($local_path) written \(($selected_keys | length) key\(s\)\)"
step 6 "Building the bootstrap image"
note "The extra substituter flags stop you compiling Determinate Nix yourself."
note "--impure is needed to read /etc/hermenix/local.nix at eval time."
if (confirm "Build now? (first run can take a while)") {
^nix build --impure --no-write-lock-file --refresh $"($flake)#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 --impure --no-write-lock-file --refresh ($flake)#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 = \"($flake)\";
(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
(ansi dark_gray)# hermes installs itself automatically - give it a few minutes(ansi reset)
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 = (vsock-ssh-args $vsock_cid $guest_user "hermes")
def gssh [cmd: string] { run-argv ($ssh_base ++ [$cmd]) }
say $"Source \(read-only\): ($source)"
say $"Destination \(guest\): ($guest_user)@hermes:($dest) \(over vsock, cid ($vsock_cid)\)"
print " hermenix vm <subcommand> control the VM (start/stop/console/snapshots/backups)"
print " hermenix ctl <subcommand> drive Hermes inside the guest (identity/config/secrets/gateway)"
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+\)"
^tar -C $source -cf - . | run-argv ($ssh_base ++ [$"mkdir -p '($dest)' && tar -C '($dest)' -xf -"])
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 " # hermes installs itself automatically on first boot - if that's"
say " # already done (check: hermes-ctl units), just:"
say " # determinate-nixd login"
say " # sudo nix flake lock /etc/nixos"
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.
#
# No checkout involved anywhere: runs `nix run <flake>#hermenix -- ...`
# directly on the remote host, fetching straight from Gitea. Requires the
# remote host to have its own SSH access to Gitea already set up (the same
# access it would need for a git clone, so nothing new).
def "main remote" [
host: string # SSH target, e.g. fwdesk.lab.internal
cmd: string # the subcommand plus its own args/flags, quoted as ONE string - e.g. "setup --clean" or "migrate /var/lib/hermes"
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
] {
# `cmd` has to be a single string, not a rest param: nu's own CLI parser
# treats any bare --flag-shaped token as an attempt to match a flag on
# THIS command (main remote), even inside a rest parameter and even with
# a `--` separator - so `hermenix remote host setup --clean` fails before
# ever reaching this function. Splitting cmd back into words here (and
# re-quoting each one) sidesteps that entirely.
let words = ($cmd | split row " " | where {|w| $w != "" })
if ($words | is-empty) {
die $'usage: hermenix remote <host> "<setup|migrate> [args...]"'
}
let quoted_args = ($words | each {|a| shquote $a } | str join " ")
let remote_cmd = $"nix run --no-write-lock-file --refresh (shquote $flake)#hermenix -- ($quoted_args)"
say $"Running on ($host): ($cmd)"
^ssh -t -o StrictHostKeyChecking=accept-new $host $remote_cmd
print "run `hermenix vm` or `hermenix ctl` for their full subcommand lists."
}
-148
View File
@@ -1,148 +0,0 @@
#!/usr/bin/env nu
#
# hermes-ctl — drive Hermes itself inside the guest: its identity, config,
# secrets, and the gateway service, plus a passthrough to its own `hermes`
# CLI. For controlling the VM around it (start/stop/snapshots/backups), see
# hermes-vm instead.
#
# Installed by the hermenix NixOS module (modules/host.nix) as part of
# environment.systemPackages under cfg.cliName, wrapped with the per-host
# vsock CID, guest SSH alias, HERMES_HOME location and gateway unit name
# baked in as env vars. The defaults below match the module's own option
# defaults, so `nix run .#hermes-ctl` also works out of the box against a
# stock setup.
#
# Requires nu/lib/common.nu to be concatenated in front of this file - see
# flake.nix and modules/host.nix. Not runnable standalone.
def guest-user [] { "hermes" }
def guest-host [] { $env.HERMES_GUEST_NAME? | default "hermes" }
def vsock-cid [] { ($env.HERMES_VSOCK_CID? | default "77") | into int }
def home-dir [] { $env.HERMES_HOME_DIR? | default "/var/lib/hermes-vm/.hermes" }
def gateway-unit [] { $env.HERMES_GATEWAY_UNIT? | default "hermes-agent" }
def cli-name [] { $env.HERMES_CLI_NAME? | default "hermes-ctl" }
def guest-ssh-args [] { vsock-ssh-args (vsock-cid) (guest-user) (guest-host) }
def gssh [cmd: string] { run-argv ((guest-ssh-args) ++ [$cmd]) }
# Pull a file out of the guest, open it in your editor, push it back.
def edit-remote [remote: string, mode: string = "0644"] {
let tmp = (mktemp)
let fetched = (do -i { gssh $"cat ($remote)" } | complete)
$fetched.stdout | save -f $tmp
let before = (open --raw $tmp | hash sha256)
^($env.EDITOR? | default "vim") $tmp
if (open --raw $tmp | hash sha256) == $before {
rm $tmp
say "unchanged"
return
}
(open --raw $tmp) | gssh $"install -m ($mode) /dev/stdin ($remote)"
rm $tmp
say $"written to ($remote)"
if (confirm "restart the gateway now?") {
gssh $"systemctl --user restart (gateway-unit)"
}
}
def print-usage [] {
print -e $"(cli-name) - drive Hermes inside the guest
soul [edit] show or edit SOUL.md
memory [edit] show or edit memories/USER.md
conf [edit] show or edit config.yaml
secrets [edit|show] manage .env, keys masked by default
status | logs | restart | units
reseed overwrite identity from /etc/nixos/hermes
pull [dir] copy live identity back to the host
Anything else goes straight to the hermes CLI in the guest:
(cli-name) chat
(cli-name) update
(cli-name) sessions list"
}
def "main soul" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/SOUL.md"
} else {
gssh $"cat (home-dir)/SOUL.md"
}
}
def "main memory" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/memories/USER.md"
} else {
gssh $"cat (home-dir)/memories/USER.md"
}
}
def "main conf" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/config.yaml"
} else {
gssh $"cat (home-dir)/config.yaml"
}
}
# API keys. Mode 0600, never enters the Nix store, and not printed unless
# you ask for it by name.
def "main secrets" [action?: string] {
if $action == "edit" {
edit-remote $"(home-dir)/.env" "0600"
} else if $action == "show" {
gssh $"cat (home-dir)/.env"
} else {
gssh $"sed 's/=.*/=<set>/' (home-dir)/.env"
}
}
def "main status" [] { gssh $"systemctl --user status (gateway-unit) --no-pager" }
def "main logs" [] { run-argv ((guest-ssh-args) ++ ["-t" $"journalctl --user -u (gateway-unit) -f"]) }
def "main restart" [] { gssh $"systemctl --user restart (gateway-unit)" }
def "main units" [] { gssh "systemctl --user list-units 'hermes*' --all --no-pager" }
# Overwrite the agent's identity from the seed. Destructive: this is how you
# undo whatever it has decided about itself.
def "main reseed" [] {
warn "This overwrites SOUL.md, memories and config.yaml in the guest"
warn "with the seed from /etc/nixos/hermes. Anything Hermes has"
warn "learned and written there is lost."
if not (confirm-word "reseed" "type 'reseed' to confirm:") { die "aborted" }
gssh $"cp -rT /etc/nixos/hermes/home (home-dir) && cp -rT /etc/nixos/hermes/workspace /var/lib/hermes/workspace && systemctl --user restart (gateway-unit)"
ok "reseeded"
}
# Copy the agent's live identity back here, so you can fold what it has
# learned into the seed in guest/hermes/.
def "main pull" [dest: string = "./hermes-home"] {
mkdir $dest
(gssh $"tar -C (home-dir) --exclude=.env --exclude=sessions --exclude=state.db -cf - .") | ^tar -C $dest -xf -
say $"pulled to ($dest) (secrets and sessions excluded)"
}
def "main help" [] { print-usage; exit 1 }
# Everything not matched above goes straight to the hermes CLI in the guest,
# with a pty for interactive subcommands like `chat`.
#
# A single string, not rest args: nu's parser tries to match any bare
# --flag-shaped token against this command's own flags before it ever
# reaches a rest parameter, so `hermes-ctl chat --model x` would fail to
# parse. Quote the whole thing instead, the same way hermenix.nu's own
# `remote` subcommand has to - e.g. `hermes-ctl "chat --model x"`. ssh
# recognizes -t regardless of where it falls in its own argv, so appending
# it (and the remote words) after the destination, as here, still works.
def main [remainder: string = ""] {
if $remainder == "" {
print-usage
exit 1
}
let words = ($remainder | split row " " | where {|w| $w != "" })
run-argv ((guest-ssh-args) ++ ["-t" "hermes"] ++ $words)
}
+82
View File
@@ -0,0 +1,82 @@
# hermenix migrate — carry an existing flat HERMES_HOME into the guest.
#
# Only ever reads from the source directory. Nothing there is deleted or
# moved — the original stays a fully intact fallback.
#
# Run this AFTER setup + the host's nixos-rebuild have brought the guest up
# at least once, and `hermenix vm ssh true` succeeds.
#
# Depends on: lib/common.nu, lib/guest.nu.
# 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.
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 = (vsock-ssh-args $vsock_cid $guest_user "hermes")
def gssh [cmd: string] { run-argv ($ssh_base ++ [$cmd]) }
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+\)"
# --ignore-failed-read: a source entry can be unreadable (e.g. uid-mapped
# leftovers from a prior rootless-container deployment) without that
# aborting an otherwise-successful migration - tar still warns about it,
# it just doesn't fail the whole pipeline over it.
^tar --ignore-failed-read -C $source -cf - . | run-argv ($ssh_base ++ [$"mkdir -p '($dest)' && tar -C '($dest)' -xf -"])
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 (hermenix vm ssh):"
say $" export HERMES_HOME=($dest)"
say " # hermes installs itself automatically on first boot - if that's"
say " # already done (check: hermenix ctl units), just:"
say " # determinate-nixd login"
say " # sudo nix flake lock /etc/nixos"
say " # hermes setup"
say " # hermes gateway install"
print ""
say "Then verify with hermenix ctl status / logs before considering the old"
say "deployment retired. Decrypt secrets/hermes-env.age yourself and fold"
say $"anything relevant into ($dest)/.env \(hermenix ctl secrets edit\)."
}
+34
View File
@@ -0,0 +1,34 @@
# hermenix remote — run setup or migrate on a remote host over SSH.
#
# No checkout involved anywhere: executes `nix run <flake>#hermenix -- ...`
# directly on the remote, fetching straight from Gitea. The remote host needs
# its own SSH access to Gitea already set up (same access as a git clone).
#
# Depends on: lib/common.nu (shquote, say, die).
# 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.
def "main remote" [
host: string # SSH target, e.g. fwdesk.lab.internal
cmd: string # subcommand + its own args, quoted as ONE string — e.g. "setup --clean" or "migrate /var/lib/hermes"
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
] {
# `cmd` has to be a single string, not a rest param: nu's own CLI parser
# treats any bare --flag-shaped token as an attempt to match a flag on
# THIS command (main remote), even inside a rest parameter and even with
# a `--` separator — so `hermenix remote host setup --clean` fails before
# ever reaching this function. Splitting cmd back into words here (and
# re-quoting each one) sidesteps that entirely.
let words = ($cmd | split row " " | where {|w| $w != "" })
if ($words | is-empty) {
die $'usage: hermenix remote <host> "<setup|migrate> [args...]"'
}
let quoted_args = ($words | each {|a| shquote $a } | str join " ")
let remote_cmd = $"nix run --no-write-lock-file --refresh (shquote $flake)#hermenix -- ($quoted_args)"
say $"Running on ($host): ($cmd)"
^ssh -t -o StrictHostKeyChecking=accept-new $host $remote_cmd
}
+362
View File
@@ -0,0 +1,362 @@
# hermenix setup — guided host-side provisioning.
#
# Walks through every prerequisite check, disk creation, cache signing key,
# local.nix, image build and image write. Safe to re-run; each step checks
# what already exists. Never runs nixos-rebuild.
#
# Depends on: lib/common.nu, lib/guest.nu.
# `truncate -s` treats a bare number as bytes, not gigabytes — the size
# prompts' own defaults ("80G", "20G") make gigabytes the obvious intent, so
# normalize a bare integer answer to that rather than silently creating a
# byte-sized disk. Anything with an existing suffix passes through as-is.
def normalize-size [s: string] {
try {
let n = ($s | into int)
$"($n)G"
} catch {
$s
}
}
# 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 as priv, 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)
}
# Guided host-side setup: disks, cache signing key, /etc/hermenix/local.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. Works
# from any directory - no local checkout of this repo needed.
def "main setup" [
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
--clean # stop the VM and delete existing disk images + UEFI vars first, for a fully fresh start
] {
$env.HERMENIX_NEED_SUDO = ((^id -u | str trim) != "0")
let local_path = "/etc/hermenix/local.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 (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"
if $clean {
warn "--clean: this stops the VM and deletes the existing system/state"
warn "disk images and UEFI vars under this directory. The btrfs"
warn "subvolumes and any snapshots are left alone."
if not (confirm-word "clean" "Type 'clean' to confirm:") { die "aborted" }
do -i { priv systemctl stop hermes-vm.service } | complete | ignore
do -i { priv rm "-f" $"($base)/system/system.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/state/state.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/OVMF_VARS.fd" } | complete | ignore
# A fresh state disk means a fresh SSH host key on next boot - drop the
# stale known_hosts entry now so the next connect doesn't fail on a
# host-key mismatch. Not run through priv: this is the invoking user's
# own ~/.ssh/known_hosts, not a root-owned path.
do -i { ^ssh-keygen -R hermes } | complete | ignore
ok "cleaned existing disk images and stale known_hosts entry"
}
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
priv chown "hermes-vm:hermes-vm" $path
ok $"subvolume ($path) \(nodatacow\)"
} else {
priv mkdir "-p" $path
priv chown "hermes-vm:hermes-vm" $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)
priv chown "hermes-vm:hermes-vm" $system_img
ok $"system disk exists \(($sz)\)"
} else {
let syssize = (normalize-size (ask "System disk size" "80G"))
priv truncate "-s" $syssize $system_img
priv chown "hermes-vm:hermes-vm" $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)
priv chown "hermes-vm:hermes-vm" $state_img
ok $"state disk exists \(($sz)\)"
} else {
let statesize = (normalize-size (ask "State disk size" "20G"))
priv truncate "-s" $statesize $state_img
priv mkfs.ext4 "-q" "-L" hermes-state $state_img
priv chown "hermes-vm:hermes-vm" $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 existing = if ($local_path | path exists) {
let evaluated = (do -i { ^nix-instantiate --eval --json --strict -E $"import ($local_path)" } | complete)
if $evaluated.exit_code == 0 {
$evaluated.stdout | from json
} else {
warn $"($local_path) exists but failed to evaluate - treating as empty"
{ cachePublicKey: "", authorizedKeys: [] }
}
} else {
{ cachePublicKey: "", authorizedKeys: [] }
}
let existing_keys = ($existing.authorizedKeys? | default [])
let replace_keys = if ($existing_keys | length) > 0 {
ok $"($existing_keys | length) key\(s\) already configured in ($local_path)"
confirm "Replace them?"
} else {
true
}
mut selected_keys = $existing_keys
if $replace_keys {
mut picked = []
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)"
}
$picked = ($picked | append (open ($found | get $idx) | str trim))
}
}
}
if ($picked | is-empty) {
let pasted = ask "Paste a public key (blank to skip)"
if $pasted != "" { $picked = [$pasted] }
}
if ($picked | is-empty) {
warn "no SSH key set — you'll only be able to reach the guest with 'hermenix vm console'"
}
$selected_keys = $picked
}
step 5 $"Writing ($local_path)"
let key_lines = ($selected_keys | each {|k| $" \"($k)\"" } | str join "\n")
let content = $"# Written by `hermenix setup`. Lives on the host, not in a repo checkout -
# see guest/local.nix.example in the hermenix repo for the reference shape.
\{
cachePublicKey = \"($cache_pub)\";
authorizedKeys = [
($key_lines)
];
\}
"
let tmp = (^mktemp | str trim)
$content | save -f $tmp
priv mkdir "-p" (($local_path | path dirname))
priv cp $tmp $local_path
priv chmod 0644 $local_path
rm $tmp
ok $"($local_path) written \(($selected_keys | length) key\(s\)\)"
step 6 "Building the bootstrap image"
note "The extra substituter flags stop you compiling Determinate Nix yourself."
note "--impure is needed to read /etc/hermenix/local.nix at eval time."
if (confirm "Build now? (first run can take a while)") {
^nix build --impure --no-write-lock-file --refresh $"($flake)#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 --impure --no-write-lock-file --refresh ($flake)#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 = \"($flake)\";
(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
hermenix vm console (ansi dark_gray)# watch it boot(ansi reset)
hermenix 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
(ansi dark_gray)# hermes installs itself automatically - give it a few minutes(ansi reset)
hermes setup
hermes gateway install
Back on the host:
hermenix ctl units (ansi dark_gray)# confirm the gateway unit name(ansi reset)
hermenix ctl status
hermenix 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"
}
+10
View File
@@ -0,0 +1,10 @@
# Shared guest-connection helpers.
# Depends on: lib/common.nu (vsock-ssh-args).
# Used by both vm/ and ctl/.
def guest-user [] { "hermes" }
def guest-host [] { $env.HERMES_GUEST_NAME? | default "hermes" }
def vsock-cid [] { ($env.HERMES_VSOCK_CID? | default "77") | into int }
# Full SSH argv for the guest, shared by `vm` and `ctl` subcommands.
def ssh-args [] { vsock-ssh-args (vsock-cid) (guest-user) (guest-host) }
+39 -44
View File
@@ -1,56 +1,51 @@
#!/usr/bin/env nu
# hermenix vm — control the Hermes Agent VM itself.
#
# hermes-vm — host-side control of the Hermes Agent VM itself: start/stop,
# console, config inspection, snapshots and backups. For driving Hermes the
# agent running inside it, see hermes-ctl instead.
# Start/stop, console, config inspection, snapshots and backups.
# For driving Hermes the agent running inside the VM, see ctl/ctl.nu.
#
# Installed by the hermenix NixOS module (modules/host.nix) as part of
# environment.systemPackages, wrapped with the per-host vsock CID, guest SSH
# alias and disk layout baked in as env vars. The defaults below match the
# module's own option defaults, so `nix run .#hermes-vm` also works
# out of the box against a stock setup.
#
# Requires nu/lib/common.nu to be concatenated in front of this file - see
# flake.nix and modules/host.nix. Not runnable standalone.
# Depends on: lib/common.nu, lib/guest.nu (ssh-args).
def guest-user [] { "hermes" }
def guest-host [] { $env.HERMES_GUEST_NAME? | default "hermes" }
def vsock-cid [] { ($env.HERMES_VSOCK_CID? | default "77") | into int }
def disk-base-dir [] { $env.HERMES_DISK_BASE_DIR? | default "/var/lib/hermes-vm" }
def snap-dir [] { $"(disk-base-dir)/snapshots" }
def ssh-args [] { vsock-ssh-args (vsock-cid) (guest-user) (guest-host) }
# Run a single already-fully-formed remote command string, or open an
# interactive shell if none is given. A single string, not rest args: nu's
# parser tries to match any bare --flag-shaped token against this command's
# own flags before it ever reaches a rest parameter, so `hermes-vm ssh sudo
# foo --bar` would fail to parse. Quote the whole remote command instead, the
# same way hermenix.nu's own `remote` subcommand has to.
def gssh [cmd?: string] {
# own flags before it ever reaches a rest parameter, so `hermenix vm ssh sudo
# foo --bar` would fail to parse. Quote the whole remote command instead.
def vm-gssh [cmd?: string] {
let argv = if $cmd == null { ssh-args } else { (ssh-args) ++ [$cmd] }
run-argv $argv
}
def usage [] {
"usage: hermes-vm {ssh [cmd]|console|config|config-pull [dir]|start|stop|restart|snapshot|snapshots|rollback <snap>|backup|backups}"
def "main vm" [] {
print "usage: hermenix vm <subcommand>"
print ""
print " ssh [cmd] open a shell or run a single command in the guest"
print " console follow the VM's journal output (journalctl -f)"
print " start systemctl start hermes-vm"
print " stop systemctl stop hermes-vm"
print " restart systemctl restart hermes-vm"
print " config show current generation, history and git status"
print " config-pull [dir] copy the guest's /etc/nixos here for reading/diffing"
print " snapshot trigger a state-disk snapshot now"
print " snapshots list existing snapshots"
print " rollback <snap> restore the state disk from a snapshot"
print " backup trigger a restic backup now"
print " backups list restic snapshots"
}
def main [] {
print (usage)
}
def "main vm ssh" [cmd?: string] { vm-gssh $cmd }
def "main ssh" [cmd?: string] { gssh $cmd }
def "main vm console" [] { ^journalctl -u hermes-vm -f -o cat }
def "main console" [] { ^journalctl -u hermes-vm -f -o cat }
def "main start" [] { ^systemctl start hermes-vm }
def "main stop" [] { ^systemctl stop hermes-vm }
def "main restart" [] { ^systemctl restart hermes-vm }
def "main vm start" [] { ^systemctl start hermes-vm }
def "main vm stop" [] { ^systemctl stop hermes-vm }
def "main vm restart" [] { ^systemctl restart hermes-vm }
# What is the guest actually running right now?
def "main config" [] {
gssh 'echo "== current generation =="; \
def "main vm config" [] {
vm-gssh 'echo "== current generation =="; \
readlink -f /run/current-system; \
echo; echo "== generations =="; \
sudo nix-env --list-generations -p /nix/var/nix/profiles/system | tail -n 10; \
@@ -60,16 +55,16 @@ def "main config" [] {
git -C /etc/nixos status --short'
}
# Copy the guest's live config here for reading or diffing.
def "main config-pull" [dest: string = "./hermes-etc-nixos"] {
# Copy the guest's live NixOS config here for reading or diffing.
def "main vm config-pull" [dest: string = "./hermes-etc-nixos"] {
mkdir $dest
(gssh "tar -C /etc/nixos -cf - .") | ^tar -C $dest -xf -
(vm-gssh "tar -C /etc/nixos -cf - .") | ^tar -C $dest -xf -
say $"pulled to ($dest)"
}
def "main snapshot" [] { ^systemctl start hermes-vm-snapshot }
def "main vm snapshot" [] { ^systemctl start hermes-vm-snapshot }
def "main snapshots" [] {
def "main vm snapshots" [] {
let entries = (glob $"(snap-dir)/state-*" | where {|p| ($p | path type) == "dir" })
if ($entries | is-empty) {
say "no snapshots"
@@ -87,9 +82,9 @@ def "main snapshots" [] {
| print
}
# Restore the state disk from a snapshot. The system disk is left alone - it
# holds nothing worth restoring.
def "main rollback" [snapshot: string] {
# Restore the state disk from a snapshot. The system disk is left alone —
# it holds nothing worth restoring.
def "main vm rollback" [snapshot: string] {
let snap = $"(snap-dir)/($snapshot)"
if not ($snap | path exists) { die $"no such snapshot: ($snapshot)" }
warn "Restores Hermes's identity, memories, workspace and NixOS"
@@ -104,9 +99,9 @@ def "main rollback" [snapshot: string] {
ok "restored; previous state kept as state.old-*"
}
def "main backup" [] { ^systemctl start hermes-vm-backup }
def "main vm backup" [] { ^systemctl start hermes-vm-backup }
def "main backups" [] {
def "main vm backups" [] {
let repo = (^systemctl show hermes-vm-backup -p Environment --value
| str trim | split row " " | where {|e| $e | str starts-with "RESTIC_REPOSITORY=" }
| get 0? | default "" | str replace "RESTIC_REPOSITORY=" "")