From efe1d30ff15c6d2067c232118dc910313817e1a5 Mon Sep 17 00:00:00 2001 From: windyboy Date: Mon, 3 Aug 2026 16:23:27 +0800 Subject: [PATCH] docs: record Hermes Matrix reconfiguration --- AGENTS.md | 5 ++ docs/hermes-matrix.md | 127 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 docs/hermes-matrix.md diff --git a/AGENTS.md b/AGENTS.md index 49b5d37..cf1e26a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,10 @@ Also readable as `agent.md` (symlink → this file). 6. Default SSH access (`ssh -4 windy@`) is for focused diagnostics, imperative upstream procedures, and incident work. Prefer **IPv4** from this WSL client (AAAA often exists but IPv6 route does not). +7. Record each material VPS operation, incident, configuration change, or + verification outcome in the corresponding **Linear `vps` project**. Include + scope, action, verification, and remaining follow-up; never put passwords, + tokens, private keys, recovery keys, or private room IDs in Linear. ## Active hosts (quick map) @@ -63,6 +67,7 @@ Also readable as `agent.md` (symlink → this file). | PowerDNS upstream refs | [docs/pdns-upstream.md](docs/pdns-upstream.md) | | Matrix health | [runbooks/matrix-health.md](runbooks/matrix-health.md) | | Matrix upstream refs | [docs/matrix-upstream.md](docs/matrix-upstream.md) | +| Hermes Agent Matrix channel | [docs/hermes-matrix.md](docs/hermes-matrix.md) | | Routine Ansible operations | [runbooks/ansible-operations.md](runbooks/ansible-operations.md) | ```bash diff --git a/docs/hermes-matrix.md b/docs/hermes-matrix.md new file mode 100644 index 0000000..d54b94c --- /dev/null +++ b/docs/hermes-matrix.md @@ -0,0 +1,127 @@ +# Hermes Agent × Matrix + +Operational notes for the Hermes Agent Matrix channel hosted on `mx2.windy.me`. +This document deliberately contains no Matrix passwords, access tokens, recovery +keys, or room encryption material. + +## Deployment + +| Item | Value | +|---|---| +| Hermes host | `mx2.windy.me` | +| Hermes profile | `assistant` | +| Profile directory | `/home/windy/.hermes/profiles/assistant` | +| User service | `hermes-gateway-assistant` | +| Matrix homeserver | `https://synapse.chans.xyz` | +| Matrix identity domain | `chans.xyz` | +| Authentication | MAS local-password account, then Matrix client access token | +| Reconfiguration helper | `/home/windy/.hermes/scripts/reconfigure-hermes-matrix.sh` | + +The gateway is started as the `windy` user with: + +```bash +systemctl --user status hermes-gateway-assistant +``` + +## Configuration contract + +The Matrix channel's secret and runtime settings are in the assistant profile's +`.env`; non-secret channel policy is in `config.yaml`. + +| Environment key | Purpose | +|---|---| +| `MATRIX_HOMESERVER` | Client-server base URL | +| `MATRIX_ACCESS_TOKEN` | Hermes account's current client access token | +| `MATRIX_USER_ID` | Hermes Matrix user ID | +| `MATRIX_DEVICE_ID` | Device returned by `/account/whoami` | +| `MATRIX_ENCRYPTION` | E2EE setting (currently expected to be `true`) | +| `MATRIX_RECOVERY_KEY` | E2EE recovery material; keep secret | +| `MATRIX_HOME_ROOM` | Primary Hermes room ID | +| `MATRIX_ALLOWED_ROOMS` | Room allow-list | +| `MATRIX_ALLOWED_USERS` | Optional sender allow-list | + +`config.yaml` must agree with the environment for `matrix.allowed_rooms`. The +gateway policy currently requires a mention unless a room is explicitly listed +in `free_response_rooms`. + +## Reinstall consequence and current finding + +The Matrix deployment on `synapse.chans.xyz` is a new homeserver instance, not a +recovery of the previous database. Therefore old Matrix users, rooms, devices, +access tokens, and E2EE state cannot be reused. + +During the 2026-08-03 check: + +- the new client API at `https://synapse.chans.xyz/_matrix/client/versions` + responded successfully; +- Hermes's existing Matrix access token returned HTTP `401 M_UNKNOWN_TOKEN`; +- the old configured room ID was still an old `:chans.xyz` room and must be + replaced with a room created on the new instance. + +## Safe reconfiguration procedure + +1. Use MAS / Element Admin to create or reset the dedicated Hermes account + (normally `@hermes:chans.xyz`). Public registration is disabled. +2. Sign in as that account via a Matrix client or the client login API and obtain + a new access token. Keep it only on `mx2` in the assistant profile `.env`. +3. Create a new private encrypted room on the new homeserver, invite the intended + human users, and copy its room ID. Do not reuse the old room ID. +4. Keep the current SSH session open and run the helper from `mx2`, supplying the + new token and room ID only through its environment (not shell history or this + repository): + + ```bash + MATRIX_ACCESS_TOKEN='...' \ + MATRIX_ROOM_ID='!...:chans.xyz' \ + /home/windy/.hermes/scripts/reconfigure-hermes-matrix.sh + ``` + + It validates the token with `/account/whoami`, checks that it resolves to the + expected Hermes user, updates the Matrix environment and allow-list, stops the + gateway, moves the previous E2EE store to a timestamped backup directory, and + restarts the gateway. + +5. Verify the service and send an `@hermes` mention in the new room. Inspect only + recent service logs; do not paste them into Git because they may contain user + content or identifiers: + + ```bash + systemctl --user is-active hermes-gateway-assistant + journalctl --user -u hermes-gateway-assistant --since '5 minutes ago' --no-pager + ``` + +If validation fails, the helper exits before changing the profile or restarting +the service. The prior E2EE store is intentionally preserved rather than deleted. + +## 2026-08-03 reconfiguration record + +The Matrix server was reinstalled as a new instance, so the Hermes account needed +a newly issued client token and a newly created room. The reconfiguration was +performed with the helper above and completed successfully. + +Verified post-change: + +- `hermes-gateway-assistant` is `active` on `mx2.windy.me`; +- the stored token authenticates as `@hermes:chans.xyz` and matches the stored + device ID; +- the new primary room is present in `MATRIX_HOME_ROOM` and + `MATRIX_ALLOWED_ROOMS` (the room ID stays in the private host profile rather + than this repository); +- the Hermes account is joined to that room; +- the prior Matrix E2EE store was moved to a timestamped backup directory below + `/home/windy/.hermes/profiles/assistant/platforms/matrix/` before restart. + +The final functional check is to send an `@hermes` mention from an allowed +member in the new room and confirm the gateway replies. Rotate the token after +any accidental disclosure, then repeat the helper procedure with the replacement +token. + +## References + +- Matrix host facts: [`hosts/synapse.chans.xyz.md`](../hosts/synapse.chans.xyz.md) +- Matrix deployment and upstream index: [`matrix-upstream.md`](matrix-upstream.md) +- Matrix health checks: [`runbooks/matrix-health.md`](../runbooks/matrix-health.md) +- [Matrix Client-Server API: account whoami](https://spec.matrix.org/latest/client-server-api/#get_matrixclientv3accountwhoami) +- [Matrix Client-Server API: login](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login) +- [Matrix room creation API](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3createroom) +- [Element Server Suite documentation](https://element-hq.github.io/ess-helm/)