hermes-agent/docs/matrix-setup.md

Matrix Integration Setup Guide

Connect Hermes Agent to any Matrix homeserver for sovereign, encrypted messaging.

Prerequisites

• Python 3.10+
• matrix-nio SDK: pip install "matrix-nio[e2e]"
• For E2EE: libolm C library (see below)

Option A: matrix.org Public Homeserver (Testing)

Best for quick evaluation. No server to run.

1. Create a Matrix Account

Go to https://app.element.io and create an account on matrix.org. Choose a username like @hermes-bot:matrix.org.

2. Get an Access Token

The recommended auth method. Token avoids storing passwords and survives password changes.

# Using curl (replace user/password):
curl -X POST 'https://matrix-client.matrix.org/_matrix/client/v3/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "m.login.password",
    "user": "your-bot-username",
    "password": "your-password"
  }'

Look for access_token and device_id in the response.

Alternatively, in Element: Settings -> Help & About -> Advanced -> Access Token.

3. Set Environment Variables

Add to ~/.hermes/.env:

MATRIX_HOMESERVER=https://matrix-client.matrix.org
MATRIX_ACCESS_TOKEN=syt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MATRIX_USER_ID=@hermes-bot:matrix.org
MATRIX_DEVICE_ID=HERMES_BOT

4. Install Dependencies

pip install "matrix-nio[e2e]"

5. Start Hermes Gateway

hermes gateway

Option B: Self-Hosted Homeserver (Sovereignty)

For full control over your data and encryption keys.

Popular Homeservers

• Synapse (reference impl): https://github.com/element-hq/synapse
• Conduit (lightweight, Rust): https://conduit.rs
• Dendrite (Go): https://github.com/matrix-org/dendrite

1. Deploy Your Homeserver

Follow your chosen server's documentation. Common setup with Docker:

# Synapse example:
docker run -d --name synapse \
  -v /opt/synapse/data:/data \
  -e SYNAPSE_SERVER_NAME=your.domain.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest

2. Create Bot Account

Register on your homeserver:

# Synapse: register new user (run inside container)
docker exec -it synapse register_new_matrix_user http://localhost:8008 \
  -c /data/homeserver.yaml -u hermes-bot -p 'secure-password' --admin

3. Configure Hermes

Set in ~/.hermes/.env:

MATRIX_HOMESERVER=https://matrix.your.domain.com
MATRIX_ACCESS_TOKEN=<obtain via login API>
MATRIX_USER_ID=@hermes-bot:your.domain.com
MATRIX_DEVICE_ID=HERMES_BOT

Environment Variables Reference

Variable	Required	Description
MATRIX_HOMESERVER	Yes	Homeserver URL (e.g. https://matrix.org)
MATRIX_ACCESS_TOKEN	Yes*	Access token (preferred over password)
MATRIX_USER_ID	With password	Full user ID (@user:server)
MATRIX_PASSWORD	Alt*	Password (alternative to token)
MATRIX_DEVICE_ID	Recommended	Stable device ID for E2EE persistence
MATRIX_ENCRYPTION	No	Set true to enable E2EE
MATRIX_ALLOWED_USERS	No	Comma-separated allowed user IDs
MATRIX_HOME_ROOM	No	Room ID for cron/notifications
MATRIX_REACTIONS	No	Enable processing reactions (default: true)
MATRIX_REQUIRE_MENTION	No	Require @mention in rooms (default: true)
MATRIX_FREE_RESPONSE_ROOMS	No	Room IDs exempt from mention requirement
MATRIX_AUTO_THREAD	No	Auto-create threads (default: true)

* Either MATRIX_ACCESS_TOKEN or MATRIX_USER_ID + MATRIX_PASSWORD is required.

Config YAML Entries

Add to ~/.hermes/config.yaml under a matrix: key for declarative settings:

matrix:
  require_mention: true
  free_response_rooms:
    - "!roomid1:matrix.org"
    - "!roomid2:matrix.org"
  auto_thread: true

These override to env vars only if the env var is not already set.

End-to-End Encryption (E2EE)

E2EE protects messages so only participants can read them. Hermes uses matrix-nio's Olm/Megolm implementation.

1. Install E2EE Dependencies

# macOS
brew install libolm

# Ubuntu/Debian
sudo apt install libolm-dev

# Then install matrix-nio with E2EE support:
pip install "matrix-nio[e2e]"

2. Enable Encryption

Set in ~/.hermes/.env:

MATRIX_ENCRYPTION=true
MATRIX_DEVICE_ID=HERMES_BOT

3. How It Works

• On first connect, Hermes creates a device and uploads encryption keys.
• Keys are stored in ~/.hermes/platforms/matrix/store/.
• On shutdown, Megolm session keys are exported to exported_keys.txt.
• On next startup, keys are imported so the bot can decrypt old messages.
• The MATRIX_DEVICE_ID ensures the bot reuses the same device identity across restarts. Without it, each restart creates a new "device" in Matrix and old keys become unusable.

4. Verifying E2EE

1. Create an encrypted room in Element.
2. Invite your bot user.
3. Send a message — the bot should respond.
4. Check logs: grep -i "e2ee\|crypto\|encrypt" ~/.hermes/logs/gateway.log

Room Configuration

Inviting the Bot

1. Create a room in Element or any Matrix client.
2. Invite the bot: /invite @hermes-bot:your.domain.com
3. The bot auto-accepts invites (controlled by MATRIX_ALLOWED_USERS).

Home Room

Set MATRIX_HOME_ROOM to a room ID for cron jobs and notifications:

MATRIX_HOME_ROOM=!abcde12345:matrix.org

Free-Response Rooms

Rooms where the bot responds to all messages without @mention:

MATRIX_FREE_RESPONSE_ROOMS=!room1:matrix.org,!room2:matrix.org

Or in config.yaml:

matrix:
  free_response_rooms:
    - "!room1:matrix.org"

Troubleshooting

"Matrix: need MATRIX_ACCESS_TOKEN or MATRIX_USER_ID + MATRIX_PASSWORD"

Neither auth method is configured. Set MATRIX_ACCESS_TOKEN in ~/.hermes/.env or provide MATRIX_USER_ID + MATRIX_PASSWORD.

"Matrix: whoami failed"

The access token is invalid or expired. Generate a new one via the login API.

"Matrix: E2EE dependencies are missing"

Install libolm and matrix-nio with E2EE support:

brew install libolm  # macOS
pip install "matrix-nio[e2e]"

"Matrix: login failed"

• Check username and password.
• Ensure the account exists on the target homeserver.
• Some homeservers require admin approval for new registrations.

Bot Not Responding in Rooms

1. Check MATRIX_REQUIRE_MENTION — if true (default), messages must @mention the bot.
2. Check MATRIX_ALLOWED_USERS — if set, only listed users can interact.
3. Check logs: tail -f ~/.hermes/logs/gateway.log

E2EE Rooms Show "Unable to Decrypt"

1. Ensure MATRIX_DEVICE_ID is set to a stable value.
2. Check that ~/.hermes/platforms/matrix/store/ has read/write permissions.
3. Verify libolm is installed: python -c "from nio.crypto import ENCRYPTION_ENABLED; print(ENCRYPTION_ENABLED)"

Slow Message Delivery

Matrix federation can add latency. For faster responses:

• Use the same homeserver for the bot and users.
• Set MATRIX_HOME_ROOM to a local room.
• Check network connectivity between Hermes and the homeserver.

Quick Start (Automated)

Run the interactive setup script:

python scripts/setup_matrix.py

This guides you through homeserver selection, authentication, and verification.