vps/docs/hermes-matrix.md

# 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/)