Files
hermenix/setup.sh
T
ariandClaude Sonnet 5 12227460fd Initial hermex: Hermes Agent in a hardened, self-managing NixOS VM
Two-disk (system/state) btrfs-backed QEMU VM, nftables-isolated by default,
adapted from a design provided as loose files. Adds a hermesHome option to
the host module and migrate-docker-hermes.sh so an existing flat HERMES_HOME
(e.g. from a prior Docker deployment) can be carried over intact.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-15 12:20:45 -04:00

381 lines
12 KiB
Bash
Executable File

#!/usr/bin/env bash
#
# hermes-vm guided setup.
#
# Walks the steps that have to happen before `nixos-rebuild switch`:
# the disk images, the cache signing key, filling in guest/common.nix, building the
# bootstrap image and writing it to disk.
#
# Safe to re-run. Every step checks whether it is already done and offers to
# skip. Nothing is destructive without an explicit confirmation.
set -euo pipefail
# ---------------------------------------------------------------- output ---
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
B=$'\033[1m'; DIM=$'\033[2m'; R=$'\033[31m'; Y=$'\033[33m'; G=$'\033[32m'; N=$'\033[0m'
else
B=""; DIM=""; R=""; Y=""; G=""; N=""
fi
step_n=0
step() { step_n=$((step_n + 1)); printf '\n%s== %d. %s%s\n' "$B" "$step_n" "$*" "$N"; }
say() { printf ' %s\n' "$*"; }
note() { printf ' %s%s%s\n' "$DIM" "$*" "$N"; }
ok() { printf ' %s✓%s %s\n' "$G" "$N" "$*"; }
warn() { printf ' %s!%s %s\n' "$Y" "$N" "$*"; }
die() { printf '\n%serror:%s %s\n' "$R" "$N" "$*" >&2; exit 1; }
ask() { # ask VAR "prompt" "default"
local __var="$1" __prompt="$2" __default="${3:-}" __reply
if [ -n "$__default" ]; then
read -r -p " $__prompt [$__default]: " __reply || true
__reply="${__reply:-$__default}"
else
read -r -p " $__prompt: " __reply || true
fi
printf -v "$__var" '%s' "$__reply"
}
confirm() { # confirm "prompt" -> 0 if yes
local reply
read -r -p " $1 [y/N] " reply || true
case "$reply" in [yY]*) return 0 ;; *) return 1 ;; esac
}
confirm_word() { # confirm_word "word" "prompt" -> 0 if they typed the word
local reply
read -r -p " $2 " reply || true
[ "$reply" = "$1" ]
}
# ------------------------------------------------------------------ setup ---
cd "$(dirname "$(readlink -f "$0")")"
if [ "$(id -u)" -eq 0 ]; then
SUDO=""
else
command -v sudo >/dev/null || die "not root and sudo is not available"
SUDO="sudo"
fi
COMMON="guest/common.nix"
CACHE_NAME="hermes-cache-1"
SECRET_KEY="/var/lib/secrets/hermes-cache.secret"
PUBLIC_KEY="/var/lib/secrets/hermes-cache.pub"
DETERMINATE_SUB="https://install.determinate.systems"
DETERMINATE_KEY="cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM="
printf '%s\n' "$B"
cat <<'BANNER'
hermes-vm · guided setup
BANNER
printf '%s' "$N"
note "This prepares the host. It does not run nixos-rebuild — you'll paste a"
note "module snippet into your own configuration at the end."
# ------------------------------------------------------------- preflight ---
step "Checking prerequisites"
[ -f flake.nix ] && [ -f "$COMMON" ] \
|| die "run this from the hermes-vm repository root"
command -v nix >/dev/null || die "nix not found on PATH"
nix flake --help >/dev/null 2>&1 \
|| die "flakes are not enabled. Add 'experimental-features = nix-command flakes' to /etc/nix/nix.conf"
ok "nix with flakes"
command -v btrfs >/dev/null || die "btrfs-progs not found. Snapshots need it."
command -v mkfs.ext4 >/dev/null || die "mkfs.ext4 not found (e2fsprogs)"
ok "btrfs-progs"
[ -e /dev/kvm ] || die "/dev/kvm is missing. KVM is required; check virtualisation is enabled in firmware."
ok "kvm"
if command -v nixos-version >/dev/null; then
ok "host is NixOS ($(nixos-version | cut -d' ' -f1))"
else
warn "this host does not look like NixOS — the module expects NixOS"
fi
# ----------------------------------------------------------------- disks ---
step "Guest disks"
note "Two disks, deliberately:"
note " system - NixOS and the Nix store. Big, churny, rebuildable. Not backed up."
note " state - identity, memories, workspace, /etc/nixos. Small. Snapshotted."
ask BASE "Directory for the disk images" "/var/lib/hermes-vm"
FSTYPE="$(stat -f -c %T "$(dirname "$BASE")" 2>/dev/null || echo unknown)"
if [ "$FSTYPE" != "btrfs" ]; then
warn "$(dirname "$BASE") is $FSTYPE, not btrfs"
warn "snapshots need btrfs. Everything else works; you'd rely on backups alone."
confirm "Continue anyway?" || die "aborted"
USE_BTRFS=no
else
USE_BTRFS=yes
fi
$SUDO mkdir -p "$BASE"
make_subvol() { # make_subvol path
if [ "$USE_BTRFS" = yes ] && ! $SUDO btrfs subvolume show "$1" >/dev/null 2>&1; then
$SUDO rmdir "$1" 2>/dev/null || true
$SUDO btrfs subvolume create "$1" >/dev/null
# nodatacow BEFORE any file exists in here. Btrfs is copy-on-write and so
# is a VM writing to a disk image; stacked, the image fragments badly.
# Only applies to files created afterwards, hence the ordering.
$SUDO chattr +C "$1"
$SUDO btrfs property set "$1" compression none 2>/dev/null || true
ok "subvolume $1 (nodatacow)"
else
$SUDO mkdir -p "$1"
fi
}
make_subvol "$BASE/system"
make_subvol "$BASE/state"
$SUDO mkdir -p "$BASE/snapshots"
SYSTEM_IMG="$BASE/system/system.raw"
STATE_IMG="$BASE/state/state.raw"
# --- system disk ---
if $SUDO test -f "$SYSTEM_IMG"; then
ok "system disk exists ($($SUDO du -h --apparent-size "$SYSTEM_IMG" | cut -f1))"
SYSTEM_EXISTED=yes
else
SYSTEM_EXISTED=no
ask SYSSIZE "System disk size" "80G"
$SUDO truncate -s "$SYSSIZE" "$SYSTEM_IMG"
if [ "$USE_BTRFS" = yes ]; then
$SUDO lsattr -l "$SYSTEM_IMG" 2>/dev/null | grep -q "No_COW" \
&& ok "system disk created, nodatacow confirmed" \
|| warn "system disk created but nodatacow did NOT apply - check 'lsattr $SYSTEM_IMG'"
else
ok "system disk created"
fi
fi
# --- state disk ---
if $SUDO test -f "$STATE_IMG"; then
ok "state disk exists ($($SUDO du -h --apparent-size "$STATE_IMG" | cut -f1))"
else
ask STATESIZE "State disk size" "20G"
$SUDO truncate -s "$STATESIZE" "$STATE_IMG"
$SUDO mkfs.ext4 -q -L hermes-state "$STATE_IMG"
ok "state disk created and formatted (label: hermes-state)"
fi
# ------------------------------------------------------------- cache key ---
step "Binary cache signing key"
note "The host serves its store to the guest read-only, so the guest doesn't"
note "re-download from the internet what you already have."
if $SUDO test -f "$SECRET_KEY"; then
ok "signing key already exists"
else
$SUDO mkdir -p /var/lib/secrets
$SUDO nix-store --generate-binary-cache-key "$CACHE_NAME" "$SECRET_KEY" "$PUBLIC_KEY"
$SUDO chmod 0400 "$SECRET_KEY"
ok "generated $CACHE_NAME"
fi
CACHE_PUB="$($SUDO cat "$PUBLIC_KEY")"
say "Public key: ${DIM}${CACHE_PUB}${N}"
# nix-serve's user only exists once the module has been applied, so this is
# expected to fail on a first run.
if id nix-serve >/dev/null 2>&1; then
$SUDO chown nix-serve "$SECRET_KEY"
ok "key owned by nix-serve"
else
warn "the nix-serve user does not exist yet — that's normal on a first run"
note "after your nixos-rebuild, run:"
note " sudo chown nix-serve $SECRET_KEY"
fi
# ------------------------------------------------------------- ssh keys ----
step "SSH access to the guest"
CURRENT_KEYS="$(sed -n '/^ authorizedKeys = \[/,/^ \];/p' "$COMMON" | grep -c '^\s*"ssh-' || true)"
if [ "${CURRENT_KEYS:-0}" -gt 0 ]; then
ok "$CURRENT_KEYS key(s) already configured in $COMMON"
if confirm "Replace them?"; then CURRENT_KEYS=0; fi
fi
SELECTED_KEYS=""
if [ "${CURRENT_KEYS:-0}" -eq 0 ]; then
mapfile -t FOUND < <(ls -1 "$HOME"/.ssh/*.pub 2>/dev/null || true)
if [ "${#FOUND[@]}" -gt 0 ]; then
say "Public keys found in ~/.ssh:"
i=0
for f in "${FOUND[@]}"; do
i=$((i + 1))
note " $i) $(basename "$f") — $(cut -d' ' -f3- "$f")"
done
ask PICK "Numbers to use (space separated, or 'n' to paste one)" "1"
if [ "$PICK" != "n" ]; then
for n in $PICK; do
f="${FOUND[$((n - 1))]:-}"
[ -n "$f" ] || die "no such option: $n"
SELECTED_KEYS+=" \"$(tr -d '\n' < "$f")\"
"
done
fi
fi
if [ -z "$SELECTED_KEYS" ]; then
ask PASTED "Paste a public key (blank to skip)"
[ -n "$PASTED" ] && SELECTED_KEYS=" \"$PASTED\"
"
fi
if [ -z "$SELECTED_KEYS" ]; then
warn "no SSH key set — you'll only be able to reach the guest with 'hermes-vm console'"
fi
fi
# ------------------------------------------------------ patch common.nix ---
step "Writing $COMMON"
[ -f "$COMMON.bak" ] || cp "$COMMON" "$COMMON.bak"
note "original saved as $COMMON.bak"
# cachePublicKey
tmp="$(mktemp)"
sed 's|^\( cachePublicKey = \).*|\1"'"$CACHE_PUB"'";|' "$COMMON" > "$tmp"
mv "$tmp" "$COMMON"
ok "cachePublicKey set"
# authorizedKeys block
if [ -n "$SELECTED_KEYS" ]; then
tmp="$(mktemp)"
awk -v keys="$SELECTED_KEYS" '
/^ authorizedKeys = \[/ { print; printf "%s", keys; inblock = 1; next }
inblock && /^ \];/ { inblock = 0; print; next }
inblock { next }
{ print }
' "$COMMON" > "$tmp"
mv "$tmp" "$COMMON"
ok "authorizedKeys set ($(printf '%s' "$SELECTED_KEYS" | grep -c '^' ) key(s))"
fi
# ----------------------------------------------------------- build image ---
step "Building the bootstrap image"
note "The extra substituter flags stop you compiling Determinate Nix yourself."
if confirm "Build now? (first run can take a while)"; then
nix build .#hermes-guest-image \
--option extra-substituters "$DETERMINATE_SUB" \
--option extra-trusted-public-keys "$DETERMINATE_KEY"
ok "built"
else
say "Skipped. Run manually:"
note " nix build .#hermes-guest-image \\"
note " --option extra-substituters $DETERMINATE_SUB \\"
note " --option extra-trusted-public-keys $DETERMINATE_KEY"
fi
# ------------------------------------------------------------ write disk ---
step "Writing the bootstrap image to the system disk"
IMAGE="$(ls -1 result/*.img 2>/dev/null | head -n1 || true)"
if [ -z "$IMAGE" ]; then
warn "no image found under ./result - skipping"
note "build it, then:"
note " sudo dd if=result/nixos.img of=$SYSTEM_IMG bs=4M conv=notrunc,fsync status=progress"
else
IMG_BYTES=$(stat -Lc %s "$IMAGE")
VOL_BYTES=$($SUDO stat -c %s "$SYSTEM_IMG")
say "image: $IMAGE ($((IMG_BYTES / 1024 / 1024)) MiB)"
say "target: $SYSTEM_IMG ($((VOL_BYTES / 1024 / 1024 / 1024)) GiB)"
[ "$IMG_BYTES" -le "$VOL_BYTES" ] || die "image is larger than the system disk"
if [ "$SYSTEM_EXISTED" = yes ]; then
warn "the system disk already existed. Writing the image replaces the"
warn "guest OS. Hermes's identity and memories live on the STATE disk and"
warn "are untouched, but anything it installed outside /var/lib/hermes is lost."
fi
if confirm_word "overwrite" "Type 'overwrite' to write the image:"; then
# notrunc so the file keeps its full size; the image is smaller than the disk
$SUDO dd if="$IMAGE" of="$SYSTEM_IMG" bs=4M conv=notrunc,fsync status=progress
ok "written"
else
say "Skipped."
fi
fi
# ----------------------------------------------------------- next steps ----
UPLINK="$(ip route get 1.1.1.1 2>/dev/null | sed -n 's/.* dev \([^ ]*\).*/\1/p' | head -n1)"
UPLINK="${UPLINK:-eno1}"
step "Next: add the module to your system flake"
cat <<EOF
${DIM}# flake.nix${N}
inputs.hermes-vm.url = "path:$(pwd)";
${DIM}# then in your modules list${N}
hermes-vm.nixosModules.default
${DIM}# configuration.nix${N}
services.hermesVm = {
enable = true;
disk.baseDir = "$BASE";
network.externalInterface = "$UPLINK";
vcpu = 4;
mem = 8192;
};
EOF
note "detected uplink: $UPLINK — check that's right before rebuilding"
cat <<EOF
Then:
sudo nixos-rebuild switch
hermes-vm console ${DIM}# watch it boot${N}
hermes-vm ssh ${DIM}# get in${N}
Inside the guest, in this order:
lsblk -f ${DIM}# CHECK LABELS match guest/hardware.nix${N}
determinate-nixd login ${DIM}# FlakeHub Cache${N}
sudo nix flake lock /etc/nixos
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup
hermes gateway install
Back on the host:
hermes-ctl units ${DIM}# confirm the gateway unit name${N}
hermes-ctl status
hermes-ctl soul
EOF
warn "Check the disk labels before the guest's first nixos-rebuild. If they"
warn "don't match guest/hardware.nix, the first self-rebuild produces a"
warn "system that won't boot."
printf '\n%s✓ host setup complete%s\n\n' "$G" "$N"