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.

```bash
# 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`:

```bash
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

```bash
pip install "matrix-nio[e2e]"
```

### 5. Start Hermes Gateway

```bash
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:

```bash
# 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:

```bash
# 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`:

```bash
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:

```yaml
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

```bash
# 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`:

```bash
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:

```bash
MATRIX_HOME_ROOM=!abcde12345:matrix.org
```

### Free-Response Rooms

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

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

Or in config.yaml:

```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:

```bash
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:

```bash
python scripts/setup_matrix.py
```

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