Files

Alexander Whitestone 56f5df8ade feat(matrix): Add fleet ops channel documentation

Part of #274. Comprehensive guide for setting up Matrix fleet ops channel to replace Telegram notifications.

2026-04-14 00:34:56 +00:00

8.0 KiB

Raw Blame History

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

# 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

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

Room Configuration

Inviting the Bot

Create a room in Element or any Matrix client.
Invite the bot: /invite @hermes-bot:your.domain.com
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"

Fleet Ops Channel (Phase 4)

The fleet ops channel replaces Telegram for system notifications, cron job results, and operational alerts.

1. Create Fleet Ops Room

Open Element (or any Matrix client)
Create a new room named "Fleet Ops" or "Hermes Ops"
Set room to invite-only (not public)
Invite your bot: @hermes-bot:your.domain.com
Get the room ID from Room Settings -> Advanced -> Internal Room ID
- Format: !randomstring:your.domain.com

2. Configure Environment