Files
hermenix/guest/common.nix
T
2026-09-17 14:14:14 -04:00

362 lines
14 KiB
Nix

{
lib,
pkgs,
modulesPath,
...
}:
let
# These must match services.hermenix.* on the host. If you changed the
# defaults there, change them here too before building the image.
hostAddress = "10.77.0.1";
guestAddress = "10.77.0.2";
prefixLength = 24;
cachePort = 5000;
# 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 != "";
# Shared between environment.systemPackages (the interactive PATH) and
# hermes-install's own `path` (below). environment.systemPackages does NOT
# propagate into systemd services' PATH on its own - a bare `curl` inside
# a systemd script only resolves if the unit is explicitly given a `path`,
# which is what actually failed here (confirmed live: "curl: command not
# found", then separately "sh: command not found" from the upstream
# installer's uv-install step, both from inside hermes-install despite the
# tools existing in systemPackages). `bash` is included explicitly because
# its output provides `bin/sh` (the same symlink NixOS's own `/bin/sh`
# compat path points at) - nothing else in this list provides a bare `sh`.
# The rest of the coreutils-adjacent tools are a baseline so the next
# third-party install script that shells out to some common Unix tool by
# bare name doesn't trigger another one of these round-trips.
hermesInstallDeps = with pkgs; [
git
curl
jq
ripgrep
fd
tree
htop
uv
nodejs
ffmpeg
direnv
nix-direnv
nix-output-monitor
gcc
gnumake
pkg-config
python3
xz
bash
coreutils
gnutar
gzip
which
gnugrep
gnused
gawk
findutils
];
in
{
# Both disks are virtio-blk, including the one this very image boots from
# (see modules/host.nix's qemu invocation) - so this has to be here, not
# only in hardware.nix. hardware.nix is excluded from this image's build
# (nixos-generators supplies its own partitioning/bootloader instead), but
# driver support for the VM environment itself is needed either way.
imports = [ (modulesPath + "/profiles/qemu-guest.nix") ];
boot.initrd.availableKernelModules = [
"virtio_pci"
"virtio_blk"
"virtio_scsi"
"ahci"
"sd_mod"
"xhci_pci"
];
networking.hostName = "hermes";
# =====================================================================
# The state disk.
#
# Second virtio disk, holding everything that cannot be rebuilt: Hermes's
# identity and memories, its workspace, and the NixOS config it maintains
# for itself. The system disk holds NixOS and the Nix store and is
# deliberately disposable.
#
# neededForBoot so it is mounted in the initrd, before activation runs and
# tries to seed into it.
# =====================================================================
fileSystems."${stateDir}" = {
device = "/dev/disk/by-label/hermes-state";
fsType = "ext4";
neededForBoot = true;
options = [
"defaults"
"noatime"
];
};
# =====================================================================
# Seed identity and configuration on first boot, then get out of the way.
#
# FIRST BOOT ONLY, deliberately. Hermes rewrites SOUL.md, its memories and
# its own NixOS config as it goes - that is the point of the thing. Copying
# the seed over it on every rebuild would quietly delete everything it had
# worked out. Use `hermes-ctl reseed` when you actually mean to overwrite.
# =====================================================================
system.activationScripts.seedHermesState = {
deps = [
"users"
"groups"
];
text = ''
install -d -o hermes -g hermes -m 0750 ${stateDir}
install -d -o hermes -g hermes -m 0750 ${stateDir}/workspace
if [ ! -e ${stateDir}/.seeded ]; then
install -d -o hermes -g hermes -m 0750 ${stateDir}/.hermes
install -d -o hermes -g hermes -m 0755 ${stateDir}/nixos
cp -rTn ${./.} ${stateDir}/nixos
cp -rTn ${./hermes/home} ${stateDir}/.hermes
cp -rTn ${./hermes/workspace} ${stateDir}/workspace
chmod -R u+w ${stateDir}/nixos ${stateDir}/.hermes ${stateDir}/workspace
chown -R hermes:hermes ${stateDir}/nixos ${stateDir}/.hermes ${stateDir}/workspace
# Git history here is the agent's cheapest undo, and it stops
# nixos-rebuild complaining about an untracked flake.
if [ ! -d ${stateDir}/nixos/.git ]; then
${pkgs.git}/bin/git -C ${stateDir}/nixos init -q -b main
${pkgs.git}/bin/git -C ${stateDir}/nixos add -A
${pkgs.git}/bin/git -C ${stateDir}/nixos \
-c user.name=seed -c user.email=seed@localhost \
commit -q -m "seed configuration from bootstrap image"
chown -R hermes:hermes ${stateDir}/nixos/.git
fi
touch ${stateDir}/.seeded
chown hermes:hermes ${stateDir}/.seeded
fi
# /etc/nixos points at the state disk, so the config is snapshotted and
# backed up along with everything else the agent owns.
#
# /etc/nixos is a real directory by default on NixOS, not a symlink or
# missing path - `ln -sfn` only replaces an existing LINKNAME in place
# if it's already a symlink; against a plain directory it instead
# creates the link *inside* it (`/etc/nixos/nixos -> ...`), leaving
# /etc/nixos itself untouched. rm -rf first so this is idempotent
# either way.
rm -rf /etc/nixos
ln -sfn ${stateDir}/nixos /etc/nixos
'';
};
# =====================================================================
# Networking: static, resolvers that are not the host.
# =====================================================================
networking.useNetworkd = true;
systemd.network.enable = true;
systemd.network.networks."10-eth" = {
matchConfig.Type = "ether";
address = [ "${guestAddress}/${toString prefixLength}" ];
routes = [ { Gateway = hostAddress; } ];
networkConfig.DNS = [
"9.9.9.9"
"149.112.112.112"
];
};
networking.nameservers = [
"9.9.9.9"
"149.112.112.112"
];
services.openssh = {
enable = true;
settings.PasswordAuthentication = false;
settings.PermitRootLogin = "no";
};
networking.firewall.allowedTCPPorts = [ 22 ];
# Lets the host fsfreeze before taking a snapshot.
services.qemuGuest.enable = true;
# =====================================================================
# Nix
#
# Determinate Nix owns /etc/nix/nix.conf and their docs are explicit that
# nix.custom.conf is the only supported place for your own settings. So
# there is no nix.settings block here, and no nix.gc either: determinate-nixd
# runs the collector itself.
#
# If the Determinate NixOS module on your version manages this file itself,
# drop this block and use its option instead. The documented nix-darwin
# equivalent is determinateNix.customSettings; the NixOS module's own option
# names are not published, so this writes the file directly.
# =====================================================================
environment.etc."nix/nix.custom.conf".text = ''
trusted-users = root hermes
extra-experimental-features = nix-command flakes
extra-substituters = https://cache.flakehub.com${lib.optionalString useHostCache " http://${hostAddress}:${toString cachePort}"}
extra-trusted-public-keys = cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM=${lib.optionalString useHostCache " ${cachePublicKey}"}
'';
# Keep enough generations that a bad self-rebuild is one boot-menu entry
# away from being undone.
boot.loader.systemd-boot.configurationLimit = lib.mkDefault 20;
# =====================================================================
# The agent's account
#
# Inside the VM the agent is effectively root. That is the point: the VM
# is the boundary, not the account. It can rebuild the system, open ports,
# add services, and none of it reaches the host.
# =====================================================================
users.users.hermes = {
isNormalUser = true;
home = stateDir;
createHome = false; # the state disk is mounted here and seeded above
linger = true;
group = "hermes";
extraGroups = [
"wheel"
"systemd-journal"
];
openssh.authorizedKeys.keys = authorizedKeys;
};
users.groups.hermes = { };
security.sudo.wheelNeedsPassword = false;
# =====================================================================
# Hermes itself
#
# Installed with upstream's own installer rather than the Nix flake, so
# that `hermes update` works natively and the agent owns its own config.
# Upstream classes Nix/NixOS as a best-effort Tier 2 platform; inside a VM
# built to contain mess, taking the supported path is the cheaper trade.
#
# The installer itself runs automatically on first boot (below) - it
# supports a fully unattended mode and has no need for operator input.
# `hermes setup` and `hermes gateway install` do need real input (model
# provider, API keys, messaging platform tokens), so those stay manual:
# hermes setup
# hermes gateway install
# loginctl enable-linger hermes
# =====================================================================
systemd.services.hermes-install = {
description = "Install the Hermes Agent CLI (first boot only)";
after = [ "network-online.target" ];
wants = [ "network-online.target" ];
wantedBy = [ "multi-user.target" ];
unitConfig.ConditionPathExists = "!${stateDir}/.hermes-installed";
path = hermesInstallDeps;
serviceConfig = {
Type = "oneshot";
User = "hermes";
Restart = "on-failure";
RestartSec = 30;
};
script = ''
set -euo pipefail
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \
| ${pkgs.bash}/bin/bash -s -- --non-interactive --skip-setup
touch ${stateDir}/.hermes-installed
'';
};
programs.nix-ld = {
enable = true;
libraries = with pkgs; [
stdenv.cc.cc
zlib
openssl
curl
libxml2
libxslt
glib
nss
nspr
at-spi2-core
cups
dbus
expat
libGL
libdrm
mesa
alsa-lib
];
};
environment.systemPackages = hermesInstallDeps;
# hermes has createHome = false (its home is the state disk, seeded above,
# not NixOS's usual skeleton) so it never gets a ~/.bashrc to append to.
# Upstream's installer puts the `hermes` launcher in ~/.local/bin and says
# as much ("Could not detect shell config file to add ~/.local/bin to
# PATH"). This option adds it via /etc/set-environment (PAM, every login
# session) instead of relying on a per-user dotfile that will never exist
# here. Same option hl-fwdesk.nix already sets on the physical host.
environment.localBinInPath = true;
programs.direnv = {
enable = true;
nix-direnv.enable = true;
};
environment.etc."hermes/ENVIRONMENT.md".text = ''
You run inside a NixOS virtual machine called "hermes". Facts about your
own environment that are easy to get wrong:
- You have your own /nix/store on your own disk. Changes persist across
reboots. `sudo nixos-rebuild switch --flake /etc/nixos#hermes` is a
real, durable change to this machine.
- /etc/nixos is yours. Edit it, commit it, rebuild from it.
- If a rebuild breaks the system, the previous generation is in the boot
menu. The operator also has snapshots of the state disk underneath that.
- Per-project environments go in a flake.nix in the project directory,
used via `nix develop` or direnv. Do not install things globally.
- This machine runs Determinate Nix. /etc/nix/nix.conf belongs to it and
must not be edited. Custom Nix settings go in /etc/nix/nix.custom.conf,
which is managed from /etc/nixos. Lazy trees are on by default, so flake
evaluation is much cheaper here than on stock Nix.
- Substituters: FlakeHub Cache, then the operator's host cache, then
cache.nixos.org. If FlakeHub Cache starts missing, the login has probably
expired; tell the operator rather than trying to re-auth yourself.
- This machine has two disks. Everything under /var/lib/hermes - your
identity, memories, workspace, and /etc/nixos, which is a symlink into
it - is on the state disk, which the operator snapshots and backs up.
Everything else, including the whole Nix store, is on a disposable
system disk that is never backed up because it can be rebuilt. Do not
keep anything you care about outside /var/lib/hermes.
- Your identity is ~/.hermes/SOUL.md and it is yours to edit. It was
seeded once on first boot and is never overwritten by a rebuild, so
changes you make there survive. Same for ~/.hermes/memories/.
- This file is regenerated on every system rebuild. Editing it is
pointless; it will be replaced. Put durable notes in SOUL.md.
- The skill at ~/.hermes/skills/nixos-self-config covers how to change
this machine safely. Read it before your first rebuild.
- You have no route to the host or to any local network. Public internet
only, plus a read-only Nix binary cache on ${hostAddress}.
- Never put a secret in a Nix expression. Everything in the store is
world-readable. Use ${stateDir}/.secrets.env and chmod 0600.
'';
system.stateVersion = "25.11";
}