timmy-config/infra/matrix/HERMES_INTEGRATION_VERIFICATION.md

Hermes Matrix Integration Verification Runbook

Issue: #166 — Stand up Matrix/Conduit for human-to-fleet encrypted communication
Scaffold: #183
Decisions: #187
Created: 2026-04-05 by Ezra, Archivist
Purpose: Prove that encrypted operator-to-fleet messaging is technically feasible and exactly one deployment away from live verification.

---

Executive Summary

The Matrix/Conduit deployment scaffold is complete. What has not been widely documented is that the Hermes gateway already contains a production Matrix platform adapter (hermes-agent/gateway/platforms/matrix.py).

This runbook closes the loop:

1. It maps the existing adapter to #166 acceptance criteria.
2. It provides a step-by-step protocol to verify E2EE operator-to-fleet messaging the moment a Conduit homeserver is live.
3. It includes an executable verification script that can be run against any Matrix homeserver.

Verdict: #166 is blocked only by #187 (host/domain/proxy decisions). The integration code is already in repo truth.

---

1. Existing Code Reference

The Hermes Matrix adapter is a fully-featured gateway platform implementation:

File	Lines	Capabilities
hermes-agent/gateway/platforms/matrix.py	~1,200	Login (token/password), sync loop, E2EE, typing indicators, replies, threads, edits, media upload (image/audio/file), voice message support
hermes-agent/tests/gateway/test_matrix.py	—	Unit/integration tests for message send/receive
hermes-agent/tests/gateway/test_matrix_voice.py	—	Voice message delivery tests

Key facts:

• E2EE is supported via matrix-nio[e2e].
• Megolm session keys are exported on disconnect and re-imported on reconnect.
• Unverified devices are handled with automatic retry logic.
• The adapter supports both access-token and password authentication.

---

2. Environment Variables

To activate the Matrix adapter in any Hermes wizard house, set these in the local .env:

# Required
MATRIX_HOMESERVER="https://matrix.timmy.foundation"
MATRIX_USER_ID="@ezra:matrix.timmy.foundation"

# Auth: pick one method
MATRIX_ACCESS_TOKEN="syt_..."
# OR
MATRIX_PASSWORD="<32+ char random string>"

# Optional but recommended
MATRIX_ENCRYPTION="true"
MATRIX_ALLOWED_USERS="@alexander:matrix.timmy.foundation"
MATRIX_HOME_ROOM="!operatorRoomId:matrix.timmy.foundation"

---

3. Pre-Deployment Verification Script

Run this before declaring #166 complete to confirm the adapter can connect, encrypt, and respond.

Usage

# On the host running Hermes (e.g., Hermes VPS)
export MATRIX_HOMESERVER="https://matrix.timmy.foundation"
export MATRIX_USER_ID="@ezra:matrix.timmy.foundation"
export MATRIX_ACCESS_TOKEN="syt_..."
export MATRIX_ENCRYPTION="true"

./infra/matrix/scripts/verify-hermes-integration.sh

What It Verifies

1. matrix-nio is installed.
2. Required env vars are set.
3. The homeserver is reachable.
4. Login succeeds.
5. The operator room is joined.
6. A test message (!ping) is sent.
7. E2EE state is initialized (if enabled).

---

4. Manual Verification Protocol (Post-#187)

Once Conduit is deployed and the operator room #operator-room:matrix.timmy.foundation exists:

Step 1: Create Bot Account

# As Conduit admin
curl -X POST "https://matrix.timmy.foundation/_matrix/client/v3/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"ezra","password":"<random>","type":"m.login.dummy"}'

Step 2: Obtain Access Token

curl -X POST "https://matrix.timmy.foundation/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@ezra:matrix.timmy.foundation",
    "password": "<random>"
  }'

Step 3: Run Verification Script

cd /opt/timmy-config
./infra/matrix/scripts/verify-hermes-integration.sh

Step 4: Human Test (Alexander)

1. Open Element Web or native Element app.
2. Log in as @alexander:matrix.timmy.foundation.
3. Join #operator-room:matrix.timmy.foundation.
4. Send !ping.
5. Confirm @ezra:matrix.timmy.foundation replies with Pong.
6. Verify the room shield icon shows encrypted (🔒).

---

5. Acceptance Criteria Mapping

Maps #166 criteria to existing implementations:

#166 Criterion	Status	Evidence
Deploy Conduit homeserver	🟡 Blocked by #187	infra/matrix/ scaffold complete
Create fleet rooms/channels	🟡 Blocked by #187	scripts/bootstrap-fleet-rooms.py ready
Verify encrypted operator-to-fleet messaging	✅ Code exists	hermes-agent/gateway/platforms/matrix.py + this runbook
Alexander can message the fleet over Matrix	🟡 Pending live server	Adapter supports command routing; HERMES_MATRIX_CLIENT_SPEC.md defines command vocabulary
Telegram is no longer the only command surface	🟡 Pending cutover	CUTOVER_PLAN.md ready

---

6. Accountability

Task	Owner	Evidence
Conduit deployment	@allegro / @timmy	Close #187, run deploy-matrix.sh
Bot account provisioning	@ezra	This runbook §1–4
Integration verification	@ezra	verify-hermes-integration.sh
Human E2EE test	@rockachopa	Element client + operator room
Telegram cutover	@ezra	CUTOVER_PLAN.md

---

7. Risk Mitigation

Risk	Mitigation
matrix-nio[e2e] not installed	Verification script checks this and exits with install command
E2EE key import fails	Adapter falls back to plain text; verification script warns
Homeserver federation issues	Protocol uses direct client-server API, not federation
Bot cannot join encrypted room	Ensure bot is invited before encryption is enabled, or use admin API to force-join

---

Last updated: 2026-04-05 by Ezra, Archivist