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


## 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

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

### 2. Configure Environment

Add to `~/.hermes/.env`:

```bash
# Fleet ops channel
MATRIX_HOME_CHANNEL=!your-room-id:matrix.org
MATRIX_HOME_CHANNEL_NAME=Fleet Ops
```

### 3. Test Fleet Ops

```bash
# Test Matrix connection
hermes matrix test

# Send a test message to fleet ops channel
hermes matrix send "Fleet ops channel test"

# Check cron job delivery
hermes cron list
# Jobs with deliver=origin will now deliver to Matrix if configured
```

### 4. Configure Cron Delivery

Cron jobs can deliver results to Matrix instead of Telegram:

```bash
# Create a job that delivers to Matrix
hermes cron create "Check system health" --schedule "every 1h" --deliver matrix:home

# Or deliver to a specific Matrix room
hermes cron create "Backup status" --schedule "every 6h" --deliver matrix:!room-id:matrix.org
```

### 5. Fleet Ops Notifications

The following notifications go to the fleet ops channel:

- **Cron job results**: Success/failure of scheduled tasks
- **System alerts**: Memory, disk, GPU usage warnings
- **Agent status**: Model changes, provider switches, errors
- **Security events**: Auth failures, suspicious activity

### 6. Crisis Room (Optional)

For urgent alerts (SOUL.md protocol), create a separate crisis room:

```bash
# Crisis channel for urgent alerts
MATRIX_CRISIS_CHANNEL=!crisis-room-id:matrix.org
MATRIX_CRISIS_CHANNEL_NAME=Crisis Room
```

### 7. Migrate from Telegram

Once Matrix is working:

1. Update cron jobs to deliver to Matrix: `--deliver matrix:home`
2. Test all critical notifications
3. Disable Telegram delivery for migrated jobs
4. Monitor both channels during transition

## Troubleshooting

### Bot not receiving messages
- Check bot has permission to read room
- Verify E2EE is working (see E2EE section)
- Check `MATRIX_HOME_CHANNEL` is set correctly

### Messages not sending
- Verify `MATRIX_ACCESS_TOKEN` is valid
- Check homeserver is reachable
- Look at gateway logs: `hermes gateway logs`

### E2EE issues
- Install: `pip install "matrix-nio[e2e]"`
- Install libolm: `brew install libolm` (macOS) or `apt install libolm-dev` (Linux)
- Restart gateway after installing