Eliminate the git-clone dependency entirely

hermenix setup/migrate/remote no longer need a local checkout anywhere:

- Host-specific settings (cache signing key, SSH keys) now live at
  /etc/hermenix/local.nix on the host itself, read via an absolute-path
  import in common.nix (--impure, deliberately - reading outside the
  flake's own source tree). No more guest/common.nix patching, no more
  guest/common.nix.bak, no more git-pull conflicts on a locally-edited
  tracked file (see the hermes-vm.service incident on hl-fwdesk).
- `setup` builds directly from the flake's own git+ssh URL by default
  (--flake to override), so it works from any directory on any host -
  dropped the "run this from the hermenix repository root" requirement
  entirely.
- `remote` now just runs `nix run <flake>#hermenix -- ...` on the target
  host directly - dropped the clone-if-missing/--dir/--repo machinery,
  since there's no checkout to manage anymore.

guest/local.nix.example documents the expected shape. Verified the
write-then-read-back round trip (nix-instantiate --eval --json) and the
simplified remote command construction against sandboxed stubs before
pushing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ariandClaude Sonnet 5 committed 2026-09-15 15:10:13 -04:00
1 parent 2078204168
commit 41ea93a28f
5 files changed
+142 -98

No files matched your search

+3
View File
@@ -0,0 +1,3 @@
# Left behind by `nix build` when run directly instead of through the CLI.
/result
/result-*
+42 -29
View File
@@ -13,26 +13,26 @@ so.
### Guided
The `hermenix` CLI (`nu/hermenix.nu`) is a flake package — no separate install
step, `nix run` builds and runs it directly from a checkout of this repo:
The `hermenix` CLI (`nu/hermenix.nu`) is a flake package — no checkout needed
anywhere. Run it straight from its Gitea URL:
```bash
nix run .#hermenix -- setup
nix run git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git#hermenix -- setup
```
(Or `nix profile install .#hermenix` once, then just `hermenix setup` from
here on. Either way, run it from this repo's root — it reads and writes
`guest/common.nix` relative to your current directory.)
(Or `nix profile install git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git#hermenix`
once, then just `hermenix setup` from here on — or get it declaratively via
the nixos-setup overlay, same as any other package. Any of these work from
any directory, on any host with SSH access to Gitea.)
Walks the host-side steps: checks prerequisites, creates the disks, generates
the cache signing key, fills in `guest/common.nix` from your SSH keys, builds
the bootstrap image and writes it to the disk. It prints the module snippet
to paste into your own configuration at the end, with your uplink interface
already filled in.
the cache signing key, writes `/etc/hermenix/local.nix` from your SSH keys,
builds the bootstrap image and writes it to the disk. It prints the module
snippet to paste into your own configuration at the end, with your uplink
interface already filled in.
Safe to re-run — every step detects what's already done and offers to skip,
and nothing destructive happens without an explicit confirmation. It keeps a
`guest/common.nix.bak`.
and nothing destructive happens without an explicit confirmation.
It deliberately stops short of `nixos-rebuild`, since that's your config.
@@ -91,20 +91,32 @@ sudo chmod 0400 /var/lib/secrets/hermes-cache.secret
cat /var/lib/secrets/hermes-cache.pub
```
### 3. Fill in `guest/common.nix`
### 3. Write `/etc/hermenix/local.nix`
Near the top:
Host-specific settings live here, not in this repo — see
`guest/local.nix.example` for the reference shape:
- `cachePublicKey` — paste the key you just printed. Leaving it empty is safe;
the guest just skips the host cache.
- `authorizedKeys` — your SSH public key.
```nix
{
cachePublicKey = "hermes-cache-1:AbCd..."; # the key you just printed; leave
# empty and the guest just skips
# the host cache
authorizedKeys = [ "ssh-ed25519 AAAA... you@laptop" ];
}
```
`sudo mkdir -p /etc/hermenix` first if it doesn't exist.
### 4. Build the image and write it to the system disk
The two extra options stop you compiling Determinate Nix from source.
The two extra substituter options stop you compiling Determinate Nix from
source. `--impure` is needed because `guest/common.nix` reads
`/etc/hermenix/local.nix` from outside this flake's own source tree —
deliberately, so the flake itself stays generic and shareable while your
settings stay on your host.
```bash
nix build .#hermes-guest-image \
nix build --impure git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git#hermes-guest-image \
--option extra-substituters https://install.determinate.systems \
--option extra-trusted-public-keys cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM=
@@ -113,11 +125,14 @@ sudo dd if=result/nixos.img of=/var/lib/hermes-vm/system/system.raw \
bs=4M conv=notrunc,fsync status=progress
```
(Building from a local checkout instead — e.g. while developing this flake —
works the same way with `.` in place of the git URL.)
### 5. Add the module to your system flake
```nix
{
inputs.hermenix.url = "path:/etc/nixos/hermenix";
inputs.hermenix.url = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git";
outputs = { nixpkgs, hermenix, ... }: {
nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
@@ -194,13 +209,11 @@ hermenix remote fwdesk.lab.internal setup
hermenix remote fwdesk.lab.internal migrate /var/lib/hermes
```
It clones this repo to `~/hermenix` on the remote host **only if that
directory doesn't already exist there**, then `cd`s into it and runs
`nix run .#hermenix -- <the rest of the command>`. An existing checkout is
never touched beyond running the command — it won't overwrite a host's own
`guest/common.nix` (cache key, authorized keys) or anything else it's
accumulated. Override the checkout path or repo URL with `--dir`/`--repo` if
you need to.
It runs `nix run <flake>#hermenix -- <the rest of the command>` directly on
the remote host — no checkout involved, on either end. The remote host does
need its own SSH access to Gitea (the same access a `git clone` would need).
Override the flake URL with `--flake` if you're pointing at a fork or a
branch.
It connects with `ssh -t`, which allocates a real pty — required for the
interactive prompts in `setup`/`migrate` to work at all over the connection.
@@ -694,10 +707,10 @@ at some directory full of `SOUL.md`, `memories/`, `sessions/`, `state.db`,
etc.):
```bash
nix run .#hermenix -- migrate /path/to/existing/HERMES_HOME
nix run git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git#hermenix -- migrate /path/to/existing/HERMES_HOME
```
Run `nix run .#hermenix -- migrate --help` for the full set of options
Run `... -- migrate --help` for the full set of options
(vsock CID, guest user, destination path, hostname rewrites). It copies —
never moves or deletes — the source data, so the original stays a safe
fallback until you've verified the new VM.
+15 -8
View File
@@ -8,14 +8,21 @@ let
prefixLength = 24;
cachePort = 5000;
# Paste the output of /var/lib/secrets/hermes-cache.pub here. Until you do,
# the guest ignores the host cache and falls back to cache.nixos.org.
cachePublicKey = ""; # e.g. "hermes-cache-1:AbCd..."
# Your SSH key, for `hermes-vm ssh`.
authorizedKeys = [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDdRSMk+ktnGcaa9KtGytKkQJ7zyHo/D2uj67snR9M2C ari@fwbook"
];
# Host-specific settings (cache signing key, your SSH key) live at a fixed
# path on the HOST, not in this repo - see local.nix.example for the shape.
# `hermenix setup` writes it there. Deliberately outside the flake's own
# source tree: this flake is meant to be built straight from its git+ssh
# URL with no local checkout at all (hence --impure, to allow reading a
# path Nix can't otherwise prove is pure), and a repo-relative file would
# either need a checkout to hold it or get baked into the immutable store
# copy Nix fetches. Falls back to safe defaults (no host cache, no SSH
# access) if it hasn't been created yet.
local =
if builtins.pathExists /etc/hermenix/local.nix
then import /etc/hermenix/local.nix
else { };
cachePublicKey = local.cachePublicKey or "";
authorizedKeys = local.authorizedKeys or [ ];
stateDir = "/var/lib/hermes";
useHostCache = cachePublicKey != "";
+18
View File
@@ -0,0 +1,18 @@
# Host-specific settings, imported by common.nix from /etc/hermenix/local.nix
# on the HOST (not from this repo - it lives outside the flake's own source
# tree on purpose, since this flake is meant to be built from its git+ssh URL
# with no local checkout at all).
#
# `hermenix setup` writes /etc/hermenix/local.nix for you. This file is just
# the reference for its shape.
{
# Output of `cat /var/lib/secrets/hermes-cache.pub` on the host, once
# generated. Leave empty (or omit the file entirely) and the guest just
# skips the host cache, falling back to cache.nixos.org.
cachePublicKey = ""; # e.g. "hermes-cache-1:AbCd..."
# Your SSH public key(s), for `hermes-vm ssh`.
authorizedKeys = [
# "ssh-ed25519 AAAA... you@laptop"
];
}
+64 -61
View File
@@ -2,9 +2,17 @@
#
# 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.
#
# Three subcommands:
# hermenix setup guided host-side setup: disks, cache signing
# key, guest/common.nix, build + write the image
# 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
@@ -71,13 +79,16 @@ def main [] {
# ------------------------------------------------------------------ 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" [] {
# 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"
] {
$env.HERMENIX_NEED_SUDO = ((^id -u | str trim) != "0")
let common = "guest/common.nix"
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"
@@ -89,9 +100,6 @@ def "main setup" [] {
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"
@@ -208,24 +216,29 @@ def "main setup" [] {
}
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)
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 {
0
{ cachePublicKey: "", authorizedKeys: [] }
}
let existing_keys = ($existing.authorizedKeys? | default [])
let replace_keys = if $current_keys > 0 {
ok $"($current_keys) key\(s\) already configured in ($common)"
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 = []
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:"
@@ -240,59 +253,50 @@ def "main setup" [] {
if $idx < 0 or $idx >= ($found | length) {
die $"no such option: ($n)"
}
$selected_keys = ($selected_keys | append (open ($found | get $idx) | str trim))
$picked = ($picked | append (open ($found | get $idx) | str trim))
}
}
}
if ($selected_keys | is-empty) {
if ($picked | is-empty) {
let pasted = ask "Paste a public key (blank to skip)"
if $pasted != "" { $selected_keys = [$pasted] }
if $pasted != "" { $picked = [$pasted] }
}
if ($selected_keys | is-empty) {
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 ($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 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."
mut built = false
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 .#hermes-guest-image --option extra-substituters $determinate_sub --option extra-trusted-public-keys $determinate_key
^nix build --impure $"($flake)#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 $" nix build --impure ($flake)#hermes-guest-image \\"
note $" --option extra-substituters ($determinate_sub) \\"
note $" --option extra-trusted-public-keys ($determinate_key)"
}
@@ -331,7 +335,7 @@ def "main setup" [] {
print $"
(ansi dark_gray)# flake.nix(ansi reset)
inputs.hermenix.url = \"path:(pwd)\";
inputs.hermenix.url = \"($flake)\";
(ansi dark_gray)# then in your modules list(ansi reset)
hermenix.nixosModules.default
@@ -468,22 +472,21 @@ def "main migrate" [
# `migrate` both act on whatever machine they run on (local disks, local
# sudo, vsock into the local guest) - this just saves the manual SSH step.
#
# Clones `--repo` to `--dir` on the remote ONLY if `--dir` doesn't already
# exist there - an existing checkout is never touched beyond running the
# command, so a host's own guest/common.nix edits (cache key, authorized
# keys) or in-progress disk state are never at risk of being overwritten.
# 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
...args: string # forwarded to the remote `hermenix` invocation
--dir: string = "hermenix" # checkout path on the remote, relative to $HOME
--repo: string = "ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
] {
if ($args | is-empty) {
die "usage: hermenix remote <host> <setup|migrate> [args...]"
}
let quoted_args = ($args | each {|a| shquote $a } | str join " ")
let remote_cmd = $"if [ ! -d (shquote $dir) ]; then git clone (shquote $repo) (shquote $dir); fi && cd (shquote $dir) && nix run .#hermenix -- ($quoted_args)"
let remote_cmd = $"nix run (shquote $flake)#hermenix -- ($quoted_args)"
say $"Running on ($host): ($args | str join ' ')"
^ssh -t -o StrictHostKeyChecking=accept-new $host $remote_cmd