Matrix

Deploy Mona as a Matrix bot for decentralized, end-to-end encrypted messaging.

Prerequisites

• A working MonoClaw installation
• A Matrix account (on any homeserver)
• The Matrix extra installed

Installation

cd ~/.monoclaw/monoclaw-runtime
uv pip install -e ".[matrix]"

1. Create a Matrix account

You can use any Matrix homeserver:

• matrix.org
• Your own Synapse server
• Element One

2. Get access token

Log in via Element Web:

1. Open Settings → Help & About
2. Scroll to Access Token
3. Click Reveal and copy the token

Or use curl:

curl -X POST https://matrix.org/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"@youruser:matrix.org","password":"yourpassword"}'

3. Configure MonoClaw

monoclaw gateway setup

Choose Matrix and enter:

• Homeserver URL (e.g., https://matrix.org)
• User ID (e.g., @monabot:matrix.org)
• Access token

Or manually:

monoclaw config set MATRIX_HOMESERVER "https://matrix.org"
monoclaw config set MATRIX_USER_ID "@monabot:matrix.org"
monoclaw config set MATRIX_ACCESS_TOKEN "syt_..."

4. Start the gateway

monoclaw gateway start

Interaction

DMs

Start a direct message with the bot account for private conversations.

Rooms

Invite the bot to a room:

/invite @monabot:matrix.org

Mention the bot or reply to her messages:

@monabot summarize the last 20 messages

Encryption

The Matrix gateway supports end-to-end encryption via mautrix:

# ~/.monoclaw/config.yaml
gateway:
  matrix:
    encryption: true
    device_name: "MonaBot"

On first start, the bot will perform device verification. Accept the verification request in Element.

Configuration

gateway:
  matrix:
    homeserver: "https://matrix.org"
    user_id: "@monabot:matrix.org"
    access_token: "${MATRIX_ACCESS_TOKEN}"
    encryption: true
    auto_join: true
    allowlist:
      - "@user1:matrix.org"

Troubleshooting