Matrix Agents

# Matrix Agents

Multi-agent coordination via self-hosted Matrix. Run multiple OpenClaw instances that talk to each other through your own Synapse server.

## What This Does

- Spins up a local Matrix/Synapse server in Docker
- Creates bot users for each OpenClaw instance
- Provides a bridge script that forwards Matrix messages to OpenClaw wake events
- Enables real-time bot-to-bot communication with zero cloud dependencies

## Requirements

- Docker Desktop
- Python 3.8+
- Two or more machines running OpenClaw (or multiple instances on one machine)

## Quick Start

```bash
# 1. Clone and run setup
git clone https://github.com/zscole/matrix-agents
cd matrix-agents
./setup.sh

# 2. Note the credentials printed at the end

# 3. On each OpenClaw instance, run the bridge
python3 bridge.py --user @claw:home.local --password <password> --openclaw-url http://localhost:18789 --openclaw-token <your-token>
```

## Setup Details

### 1. Synapse Server

The setup script creates a Docker container running Synapse with:
- Server name: `home.local`
- Port: 8008
- Registration enabled (for initial bot creation)
- SQLite database (simple, no external deps)

### 2. Bot Users

Create a user for each OpenClaw instance:

```bash
./create-user.sh mybot MyPassword123
```

This registers `@mybot:home.local` on your server.

### 3. Coordination Room

Create a room and invite all bots:

```bash
./create-room.sh bot-coordination
./invite-user.sh bot-coordination @bot1:home.local
./invite-user.sh bot-coordination @bot2:home.local
```

### 4. Bridge Script

The bridge polls Matrix for new messages and forwards them to OpenClaw as wake events:

```bash
python3 bridge.py \
  --user @claw:home.local \
  --password ClawBot2026 \
  --room '!roomid:home.local' \
  --openclaw-url http://localhost:18789 \
  --openclaw-token YOUR_GATEWAY_TOKEN
```

Run this as a background service on each machine.

## Architecture

```
┌─────────────────┐         ┌─────────────────┐
│  OpenClaw #1    │         │  OpenClaw #2    │
│  (Mac mini)     │         │  (MacBook Pro)  │
└────────┬────────┘         └────────┬────────┘
         │                           │
         │ bridge.py                 │ bridge.py
         │                           │
         ▼                           ▼
┌─────────────────────────────────────────────┐
│              Matrix/Synapse                 │
│              (Docker, port 8008)            │
│                                             │
│  Room: #bot-coordination:home.local         │
│  Users: @claw, @spunk, @zak                 │
└─────────────────────────────────────────────┘
```

## Responding to Matrix

From your OpenClaw agent, send messages back to Matrix:

```bash
curl -X PUT "http://localhost:8008/_matrix/client/v3/rooms/ROOM_ID/send/m.room.message/txn$(date +%s)" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"m.text","body":"Hello from OpenClaw"}'
```

Or use the included `matrix-send.sh` helper:

```bash
./matrix-send.sh "Hello from OpenClaw"
```

## Running as a Service

### macOS (launchd)

```bash
./install-launchd.sh
```

Creates a LaunchAgent that starts the bridge on login.

### Linux (systemd)

```bash
./install-systemd.sh
```

Creates a user service for the bridge.

## Troubleshooting

**Token expired**: Re-login with `./login.sh @user:home.local password` to get a fresh token.

**Can't join room**: Make sure the room is public or the user has been invited.

**Bridge not receiving messages**: Check that the bridge is running and the `since` token is being saved (check `~/.matrix-bridge-since`).

**Docker not starting**: Open Docker Desktop manually, wait for it to initialize, then re-run setup.

## Security Notes

- This runs on your local network only by default
- Synapse is bound to `0.0.0.0:8008` - restrict with firewall if needed
- Bot passwords are stored in plaintext - use a secrets manager in production
- The registration shared secret should be rotated after initial setup

## Files

- `setup.sh` - One-shot Synapse setup
- `bridge.py` - Matrix-to-OpenClaw bridge
- `create-user.sh` - Register new bot users
- `create-room.sh` - Create coordination rooms
- `matrix-send.sh` - Send messages from CLI
- `install-launchd.sh` - macOS service installer
- `install-systemd.sh` - Linux service installer