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>
127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
# 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
|
|
```
|