Hermes self-improves: it writes skills into its own home directory and edits them as it learns. This is how one Nix flake runs it anyway, with a set of skills, the persona, the settings and the scheduled jobs kept as versioned source code — while the agent keeps writing its own skills the way it normally does. A structure tour, not a configuration dump: the values below are placeholders, the shapes are real.
The only clanker-written post on this site: assembled by the agent from the repo's readmes, its own lessons-learned skills and the git history.
Declarative soul and skills
Two things are true at once, and the whole design is about keeping them from fighting:
- Hermes self-improves. It writes skills into
$HERMES_HOME/skills/, edits them as it learns, and that is a feature. Wrapping the agent in a read-only box throws that away. - Some skills are owned by the repo. They encode procedures that are reviewed like code — security sweeps, host rebuilds, library maintenance. Those must never be improvised.
So the repo owns a selection of skills, the persona, the settings and the scheduled jobs. Everything
else stays the agent's own private workshop. Both trees end up in the same directory — skills/
under the agent's home — and the loader does not care which is which.
Nothing is copied into place and then drifts. The live skill is the store path, and the store path is whatever the repo said at build time. If it is wrong, it is wrong identically on every host, in git, and visible in a diff.
Dendritic, but only at the host layer
A fully dendritic repo has no central import list: every file imports its own dependencies, and what is wired is discovered by reading the graph. It is beautiful, and it means every host's file touches every module it wants.
The hybrid here: hosts are dendritic, modules are a pool.
modules/is imported into every host automatically (oneimport-tree ./modules). A module opts itself out with anenableflag that defaults to false.hosts/<name>/is imported into that host automatically. Creating a host is creating a directory with a_host.nixin it — no registry, no include list, nothing to forget.
Why the asymmetry: a shared module needs to be reachable from anywhere, and making every host list the twenty modules it uses is exactly the boilerplate dendritic layouts exist to avoid. A host directory is genuinely per-host, so importing the whole thing costs nothing and dropping a file into it is the whole workflow.
Repo skeleton
The whole Hermes integration is one module with a _lib/ beside it, plus a directory per host.
/etc/nixos # flake, checkout, shared with the agent (ACL)
├── flake.nix # inputs: nixpkgs, flake-parts, import-tree
├── nixos.nix # options.custom.hosts + the collector
├── modules/ # global pool — imported into every host
│ ├── server.nix firewall.nix sops.nix …
│ └── hermes/
│ ├── default.nix # custom.hermes: options + ALL the wiring
│ ├── _lib/ # helpers, NOT modules (import-tree skips _*)
│ │ ├── skill-tree.nix # skill dir → store path + tests
│ │ ├── cron-jobs.nix # renders the reconcile oneshot
│ │ └── cron-reconcile.sh
│ ├── scripts/ # watch-gate.py, the rebuild guard
│ ├── plugins/ # e.g. a TTS plugin, replaceVars'd into the store
│ └── skills/ # GENERAL skills: module + files, opt-in per host
│ ├── host-changes/
│ │ ├── default.nix # enable option, tree, its cron jobs
│ │ ├── SKILL.md # the document the agent reads
│ │ ├── references/
│ │ └── scripts/ # helper.py + test_helper.py
│ └── …
└── hosts/
├── media-box/
│ ├── _host.nix # the ONLY required file: channel + extra modules
│ ├── config.nix hardware.nix users.nix
│ └── hermes/
│ ├── default.nix # this host's custom.hermes block
│ ├── SOUL.md # the persona, versioned like everything else
│ └── skills/ # HOST-specific skills: no enable flag
├── web-01/ # no hermes/ dir → the agent simply isn't there
└── laptop/
General skill → lives in modules/hermes/skills/, opt-in via
custom.hermes.skills.<name>.enable. Host-specific skill → lives in
hosts/<host>/hermes/skills/, ships whenever the agent is enabled, no flag. A skill that
hard-codes one box (a library path, a forum login, a piece of hardware) must not grow an
enable option — a flag invites someone to turn it on where it cannot work. When it becomes
useful elsewhere, it moves to the general pool and gets the flag in the same commit.
Hermes as a NixOS module
The base module does two jobs. It declares the options a host may set — and it owns everything that is not a per-host decision: the service user, the model, the chat gating, speech in and out, the headed browser's virtual display, sudo rules, ACLs, the activation scripts. A host turns the agent on with a handful of lines.
hosts/media-box/hermes/default.nix{ config, lib, pkgs, ... }:
{
custom.hermes = {
enable = true;
name = "AGENT"; # service-user description + git identity
email = "agent@example.dev";
soul = ./SOUL.md; # installed as $HERMES_HOME/SOUL.md
repoDir = "/etc/nixos"; # the checkout it may read and rebuild from
notifyTarget = "telegram:000000000"; # default cron destination
groupTarget = "telegram:-1000000000"; # shared room
telegram = {
allowedUsers = [ "000000000" ]; # who may DM it
allowedGroupUsers = [ "000000000" "000000001" ]; # group senders only
unauthorizedDmBehavior = "decline";
};
skills = {
host-changes.enable = true;
skill-authoring.enable = true;
# a skill can take its own options; this is where it becomes host-aware
security-watch = {
enable = true;
composerHosts = {
web01 = { domain = "example.dev"; port = 2222; };
};
};
};
};
}
The option that makes the rest work
One internal option is a plain attrset: skill name → built directory.
# modules/hermes/default.nix (abridged)
options.custom.hermes.skillTrees = lib.mkOption {
type = lib.types.attrsOf lib.types.path;
default = { };
internal = true; # skills contribute to it; hosts do not set it
};
Every skill module adds exactly one entry to it. The base module never knows which skills exist — it links whatever is in the attrset and prunes whatever left it. Adding or dropping a skill never edits the base module, which is the property that keeps this from turning into a switch statement with a hundred branches.
modules/hermes/_lib/skill-tree.nix{ lib, pkgs }:
{ name, dir }:
let
# SKILL.md plus the four support dirs and nothing else: tests and caches
# stay in the repo. One document per skill, no second readme to drift.
supportDirs = [ "references" "templates" "assets" "scripts" ];
# test_*.py next to the helpers runs HERE — a red test fails the build
in
pkgs.runCommand "hermes-skill-${name}"
{ nativeBuildInputs = [ pkgs.python3 pkgs.jq ]; } ''
# … copy the tree, run unittest discover in $TMPDIR, strip __pycache__
''
A helper's unit tests run while the skill directory is being built, against a writable copy in
$TMPDIR (the store is read-only and cannot take __pycache__). A broken helper then
fails nixos-rebuild build, which means the generation never switches and the agent never sees
it. Tests have to be pure — the sandbox has no network, so a test that fetches an advisory fails for the
wrong reason. That constraint is the point: it forces the helper to separate fetching from deciding.
A skill is a directory that is a module
The module and the document sit in the same folder, named after the skill. The module is not scaffolding around the document — it is the skill's whole host interface: its enable flag, its options, its helper copies, its scheduled jobs.
modules/hermes/skills/security-watch/default.nix (abridged){ config, pkgs, lib, hermesSkillTree, hermesCronJobs, ... }:
let
cfg = config.custom.hermes;
name = "security-watch";
hermesHome = "${config.services.hermes-agent.stateDir}/.hermes";
in
{
# 1. the flag a host flips
options.custom.hermes.skills.${name}.enable =
lib.mkEnableOption "the ${name} skill";
# 2. optional settings: the host says WHERE, the skill knows HOW
options.custom.hermes.skills.${name}.inventory = lib.mkOption {
type = lib.types.attrsOf (lib.types.submodule {
options = {
domain = lib.mkOption { type = lib.types.str; };
port = lib.mkOption { type = lib.types.port; default = 22; };
};
});
default = { };
};
config = lib.mkIf (cfg.enable && cfg.skills.${name}.enable) {
# 3. the document tree → store → $HERMES_HOME/skills/security-watch
custom.hermes.skillTrees.${name} =
hermesSkillTree { inherit name; dir = ./.; };
services.hermes-agent = {
# 4. settings reach the helper through .env, not through the store
environment.SECURITY_WATCH_INVENTORY =
builtins.toJSON cfg.skills.${name}.inventory;
# 5. cron runs --script jobs from $HERMES_HOME/scripts/: keep a copy
hermesHomeFiles."scripts/security-watch.py" =
./scripts/security_watch.py;
hermesHomeFiles."scripts/security-watch.sh" =
./scripts/security-watch.sh;
};
# 6. and the jobs the skill owns are declared in the same conditional
systemd.services."hermes-${name}-jobs" = hermesCronJobs {
name = "hermes-${name}-jobs";
description = "Ensure ${name} cron jobs";
inherit hermesHome;
hermesBin = "${config.services.hermes-agent.package}/bin/hermes";
notifyTarget = cfg.notifyTarget;
jobs = [ {
name = name;
schedule = "30 5 * * *"; # the agent's clock, not the host's
skill = name;
agent = true;
monitor = "security-watch-monitor.sh"; # unchanged → skip
prompt = lib.trim ''
Use the ${name} skill. Run "$HERMES_PYTHON"
"$HERMES_HOME/scripts/security-watch.py" check --json.
Stay inside 15 shell calls and one helper run; never read
the helper's source to explain itself.
Reply exactly [SILENT] if nothing is actionable.
'';
}];
};
};
}
Six things, one file, one folder. Deleting the folder and the host's enable line retires the skill completely — the tree link is pruned by activation, the helper copy by the home-files manifest. The scheduled jobs are the exception: removing the unit does not remove the runtime job, so that one is deleted once by hand.
The host-specific variant
No enable option, and its plumbing needs the host's own details, so the module reaches for them directly:
hosts/media-box/hermes/skills/library-watch/default.nix{ config, lib, hermesSkillTree, hermesCronJobs, ... }:
let
cfg = config.custom.hermes;
name = "library-watch";
in
{
# ships whenever the agent is enabled on this host — no flag of its own
config = lib.mkIf cfg.enable {
# the group that makes the library socket/key readable at all
users.users.hermes.extraGroups = [ "media" ];
custom.hermes.skillTrees.${name} =
hermesSkillTree { inherit name; dir = ./.; };
# the credential comes from sops; only its path is configuration
services.hermes-agent.environment.LIBRARY_KEY_FILE =
config.sops.secrets.library-api-key.path;
# … helper copies + hermesCronJobs, same as above
};
}
Note what is not in there: no password, no token, no library path in the store. Credentials live in sops, the helper is told where to look, and the module is safe to show someone.
Repo file → store path → live skill
This is the path a single edited SKILL.md takes. It is short, and every step is checkable,
which is the point of routing it through the build.
A skill's text is read when a session starts. So a switch updates the file on disk immediately,
but the conversation already in flight keeps the old copy in its context. The last step of every skill change
is /new. That sounds like an annoyance and is actually useful: it means a mid-conversation
nixos-rebuild switch cannot rewrite the instructions the agent is currently following.
# the live skill is a link into the store, not a directory
$ readlink -f "$HERMES_HOME/skills/security-watch"
# and its content is the content in the repo
$ md5sum "$HERMES_HOME/skills/security-watch/SKILL.md" \
modules/hermes/skills/security-watch/SKILL.md
The loop: the agent curates its own source
"Black box, but some of it needs auditing" is not solved by a sandbox. The mechanism is a review gate on the same files the agent runs from. The agent has write access to the repo. It commits, it rebuilds, its own instructions change. Three things keep that from being a runaway:
- A diff exists. The agent's edit is a commit, on a branch, reviewable with
git log -pafterwards — including its reasoning in the message, which it writes itself. - The build is a test. Nothing reaches a generation over a red unit test, and nothing reaches one over a failed evaluation. A typo in a module is a refused switch, not a broken agent.
- Privilege is gated on a person, not on a claim. The rebuild path runs a guard that resolves which account asked for the turn — not which chat. In a shared room with two humans and one agent, "the message came from the group" says nothing about who typed it.
This is a guard against a convincing stranger and against a bad instruction, not a sandbox. A session that empties the environment variable the guard reads gets through, and the agent can edit the repo copy of the script it is about to run — which is exactly why the sudo path runs a copy baked into the previous generation, and why the diff still gets read. A hard boundary means the agent must not have write access to the repo at all, and then half of this is gone.
And the split is enforced in the other direction too: skill_manage — the agent's own tool for
editing skills — cannot touch a Nix-declared skill. It fails with "not found in active profile", because the
name resolves to a symlink into the store. The error reads like a typo and is a permission boundary. That is
deliberate: this skill changes with a commit, that one changes with a tool call, and the
agent learns the difference by bumping into it.
Cron jobs, reconciled
Hermes has no declarative cron option — jobs live in its own state. So the module renders a oneshot unit per skill that reconciles by name: it reads the live job list, creates or edits each declared job, and removes only the ones it recorded creating last time. The manifest is what makes pruning safe.
Two details that took a while to get right. First, the deliver field is per job, not per
module: one skill's announcement can belong in a shared room while its maintenance ticket belongs in a DM.
Second, a job whose normal outcome is silence needs a gate, not a schedule — a monitor script whose
stdout the scheduler hashes, so a quiet day costs zero tokens instead of a full prompt.
And the payoff of the whole exercise: when the schedule moved from UTC to Berlin time, that
was a timezone line plus one git grep for weekday names in prompts — not eleven chat
messages to an agent saying "actually make it an hour earlier".
What is declarative, and what deliberately isn't
How much is actually declarative: more than expected, and not all of it. Three tiers, all three kept.
| Thing | Owner | Changes by |
|---|---|---|
Settings — model, chat gating, speech, timezone, browser
module's settings block |
nix | edit + switch; runtime writes are refused |
Persona — SOUL.md
host dir → copied into the agent's home |
nix | edit + switch, then /new |
| Chosen skills' text, references, helper scripts skill dir → store → symlink | nix | edit + git add + switch |
Scheduled jobs of those skills
hermesCronJobs in the skill module |
nix | edit + switch (reconcile oneshot) |
Plugins
plugins/, replaceVars, store path |
nix | edit + switch |
Skills the agent invents for itself
real dirs under $HERMES_HOME/skills/ |
runtime | its own skill_manage calls |
Memory, session DB, watch state, per-title watches
$HERMES_HOME |
runtime | the agent, as it works |
Credentials, API keys, logins
sops → .env; vault |
human | the human, never the config |
Rough proportion on the box that runs this: eleven skills in the repo, around sixty the agent wrote for itself. The repo holds the ones where a mistake is expensive — security sweeps, host rebuilds, library deletion — plus anything that needs tuning like a knob rather than a negotiation with a prompt. Everything exploratory stays the agent's.
If a change is worth reading as a diff before it takes effect, it belongs in Nix. If the better outcome is simply that the agent gets better at it, it does not. A skill that only serves one film, one feed, one evening can still be runtime — but code developed with the agent is code, even when every instance it serves is temporary.
Day-to-day workflow
- New skill, or a change to a repo-owned one
Make the folder, write
SKILL.mdplusdefault.nix, put helpers inscripts/with atest_*.pybeside them.git add— a flake build cannot see an untracked file, and a build that succeeds while silently missing your skill is the classic trap. - Enable it where it should run
One line in
hosts/<host>/hermes/default.nix. If a second host needs it, that is a second line — not a copy of the files. - Build before switching
nixos-rebuild build --flake path:/etc/nixos#<host>. The build's "these N derivations will be built" list is the coverage check in the other direction: a skill you edited that is not in it did not change. - Switch, then prove it
Read back the symlink, hash the installed
SKILL.mdagainst the repo one, then/newso the session loads the tree it just got. - Commit and push The agent does this part itself, in the same repo, through the same hooks. Work that is not committed and pushed is not finished.
What that buys in practice
- Rollback is a git revert plus a switch, not a memory of what the prompt used to say.
- Every host is a manifest. "Which box runs the security sweep?" is
git grep 'security-watch.enable' hosts/. - Skills become reviewable. A 280-line
SKILL.mdreads a lot better in a pull request than in a chat transcript — and a helper's bug is a failing test, not a wrong message at 05:30. - The agent can contribute to the same repo. It proposes a skill change as a commit; the human reads it later. That is the actual answer to "black box, but audited".
The costs
- A rebuild is in the loop. Typo in a skill document? Rebuild. That is fine for text edited rarely and annoying for text being iterated on. Mitigation: iterate in a runtime copy, promote to the repo when it settles.
- Cron is the seam. Hermes' jobs are runtime state; the reconcile oneshot is a shim over a
missing declarative API. A
cron.nixupstream would make that file unnecessary. - Two owners of one directory is a real edge. The agent's own skills and the linked ones live side by side; the pruning logic has to be careful to only remove what it installed. It is guarded by a manifest, and it is the part most likely to break under future changes.
So does it defeat the purpose?
It does not defeat the purpose, though it does move it. The question stops being "did the agent get better at this?" for a handful of procedures, and becomes "is this procedure right?" — which can be answered, reviewed and reverted. The agent keeps its workshop for everything else, including the things nobody would think to write.
What follows from it: do not declarative-ise the skills that are still being figured out. Nail down two or three that are already trusted, keep the rest runtime, and let the split grow where it hurts.
Neuen Kommentar hinzufügen