Files
hermenix/GUIDELINES.md
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

4.9 KiB

Agent Guidelines — hermex

Rules and best practices for any AI agent working in this repository. Read this file before making any changes.


Mandatory First Step — Always Present a Plan

Before making any change to this repository, you MUST present a short plan to the user and wait for their approval. This applies to every task, no matter how small.

Your plan must include:

  1. What you intend to change (files, modules, seed content)
  2. Why the change is needed
  3. How you will do it (which files you will edit, in what order)
  4. What you will NOT do (e.g., "I will not run setup.sh or build the image")

Only after the user approves the plan may you proceed with edits.


Hard Rules — Never Break These

❌ NEVER run builds or disk-writing steps — ZERO EXCEPTIONS

DO NOT RUN ANY OF THESE COMMANDS AT ANY TIME, FOR ANY REASON:

nix build
nix flake check
./setup.sh                    # unless the user is actively running it themselves with you watching
dd ... of=/var/lib/hermes-vm/**   # writing any disk image
nixos-rebuild switch / test / build  (on any host consuming this flake)

Why:

  • setup.sh creates/writes disk images and generates host secrets (a binary cache signing key) — destructive if repeated carelessly, and it's the operator's host, not yours to act on.
  • A nixos-rebuild switch on a consuming host is a live, production-affecting action — for hl-fwdesk specifically, it's the machine running the operator's actual daily-use Hermes deployment.
  • These commands can take a long time and consume real resources on a machine you don't control from here.

Your job: Write good Nix and good docs. The operator runs setup.sh, the image build, and any nixos-rebuild themselves, on the host, watching each step.

❌ NEVER run hermes-vm rollback or hermes-ctl reseed without fresh confirmation

Both are destructive to live guest state — rollback replaces the current state disk with an old snapshot; reseed overwrites SOUL.md, memories, and config.yaml with the seed. A prior approval for a different task does not carry over. Ask again, in the moment, before either.

❌ NEVER edit guest/hardware.nix's disk labels blindly

fileSystems."/" and "/boot" assume labels nixos and ESP. Getting this wrong produces a guest that won't boot after its first self-rebuild. Only change these after the operator has run lsblk -f inside the actual guest and told you the real labels.

❌ NEVER commit live secrets to guest/hermes/home

That directory is a template seed for fresh deployments — it gets copied into the guest on first boot and is world-readable in git history forever after. Real credentials belong in the guest's own ~/.hermes/.env (hermes-ctl secrets edit), never in this repo, never in the Nix store.

❌ NEVER move or delete source data during a migration

When carrying over an existing Hermes deployment (see migrate-docker-hermes.sh), only ever read from and copy the source. Leave it in place and untouched until the operator has verified the new deployment end-to-end. This is the rollback safety net — don't remove it.

❌ NEVER commit or push unless explicitly asked

Same as any other repo: describe your changes and let the operator review before committing.


Safe Operations

These are always safe to perform without asking:

  • Reading any file in this repo
  • Editing modules/host.nix to add/adjust options (gated behind mkIf cfg.enable, following the existing style)
  • Editing guest/hermes/home / guest/hermes/workspace template seed content (as long as it stays free of real secrets — see above)
  • Editing README.md / GUIDELINES.md / AGENTS.md
  • nix-instantiate --parse <file>.nix — syntax check only, no eval, no build

When In Doubt

If you are unsure whether a command is safe, assume it is NOT SAFE and don't run it. Describe what you would do and ask.


Repository Layout

hermex/
├── flake.nix              # bootstrap flake: builds the guest image, exposes nixosModules.default
├── modules/host.nix        # services.hermesVm — the host-side NixOS module
├── setup.sh                 # guided host-side setup (disks, cache key, image build)
├── migrate-docker-hermes.sh # carries an existing flat HERMES_HOME into a hermex guest
├── guest/
│   ├── flake.nix           # the GUEST's own /etc/nixos flake — belongs to the agent, not the operator
│   ├── common.nix          # guest NixOS config baked into the bootstrap image
│   ├── hardware.nix        # guest disk layout — verify labels before ever editing
│   └── hermes/
│       ├── home/           # template seed -> ~/.hermes on first boot (SOUL.md, config.yaml, memories/, skills/)
│       └── workspace/      # template seed -> ~/workspace on first boot
└── README.md                # full usage docs