Run the Hermes agent declaratively from the nix repo it is allowed to edit

15 Nov 2026

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.

/etc/nixos (git) modules/…/skills/ hosts/<h>/hermes/skills/ SOUL.md · settings · cron jobs /nix/store/hermes-skill-* read-only content one path per skill, per generation $HERMES_HOME/skills/ security-watch → symlink into the store research/ a real directory — the agent's own the live skill IS the store path — nothing is copied, nothing drifts
Fig 1 — the repo builds store paths; activation symlinks them next to the agent's own skills

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 (one import-tree ./modules). A module opts itself out with an enable flag that defaults to false.
  • hosts/<name>/ is imported into that host automatically. Creating a host is creating a directory with a _host.nix in 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.

flake.nixflake-parts mkFlake + inputs hosts/*/_host.nixnixpkgs channel + extra modules custom.hosts.<name>the collector's input collectorone nixosSystem per host modules/ (every host) ++ hosts/<n>/ (that host) files starting with _ (_host.nix, _lib/) are not modules one flake output per host: nixosConfigurations.<name>
Fig 2 — hosts declare themselves as options; a collector turns each entry into a nixosSystem

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/
the two trees, one rule

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__
''
why tests live in the derivation

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.

1 · edit skills/x/SKILL.md + scripts/*.py 2 · build nixos-rebuild build — unit tests run in the sandbox 3 · store /nix/store/…-hermes-skill-x (read-only) 4 · switch activation: ln -sfn store → $HERMES_HOME/skills/x 5 · live read when the session starts — /new loads it activation also rewrites config.yaml, copies home-files, prunes what a module dropped a running conversation keeps the text it loaded — frozen until /new git add first: a flake build cannot see an untracked file
Fig 3 — the edit-to-live path, and the boundary where it stops being instant

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.

verification commands
# 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:

  1. A diff exists. The agent's edit is a commit, on a branch, reviewable with git log -p afterwards — including its reasoning in the message, which it writes itself.
  2. 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.
  3. 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.
1 · agent edits the repo SKILL.md, helper, module in the same repo as a human 2 · commit hook checks the sender owner → pass 3 · build eval + unit tests green → switch allowed 4 · switch sudo wrapper + the store copy of the guard 5 · next session reads the new text the agent ends up running from source it wrote — and every change is in git skill_manage cannot touch these: the name resolves to a store symlink
Fig 4 — write, gate, build, link, re-read: a self-modifying agent with a commit history
the honest caveat

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.

jobs = [ … ] name · schedule · skill|script · agent · monitor · deliver declared in the skill module, beside the helper it runs hermesCronJobs renders one oneshot unit: ensure_job lines + declared list runs on every activation, matches jobs by name hermes cron list create · edit by name · remove what the manifest owns a job the module never created is never touched a job removed from nix stays a runtime job — delete it once by hand monitor script + identical stdout → the agent never starts at all
Fig 5 — declared jobs reconcile by name; the manifest scopes what may be removed

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.

ThingOwnerChanges 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.

the dividing line

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

  1. New skill, or a change to a repo-owned one Make the folder, write SKILL.md plus default.nix, put helpers in scripts/ with a test_*.py beside 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.
  2. 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.
  3. 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.
  4. Switch, then prove it Read back the symlink, hash the installed SKILL.md against the repo one, then /new so the session loads the tree it just got.
  5. 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.md reads 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.nix upstream 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.

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang target> <em> <strong> <cite> <blockquote cite> <pre> <ul type> <ol start type> <li> <dl> <dt> <dd> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.

Get a quote in 24 hours

Wether a huge commerce system, or a small business website, we will quote the project within 24h of you pressing the following button: Get quote