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:

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

Use MAS / Element Admin to create or reset the dedicated Hermes account (normally @hermes:chans.xyz). Public registration is disabled.
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.
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.
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):
```
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.
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:
```
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
Matrix deployment and upstream index: matrix-upstream.md
Matrix health checks: runbooks/matrix-health.md
Matrix Client-Server API: account whoami
Matrix Client-Server API: login
Matrix room creation API
Element Server Suite documentation

5.5 KiB Raw Blame History Unescape Escape