Matrix

Mudabbir connects to the Matrix protocol via matrix-nio. Matrix is an open, decentralized communication protocol ideal for self-hosting enthusiasts.

Setup

Create a Matrix account

Create a bot account on your Matrix homeserver (e.g., matrix.org, your own Synapse server).

Get an access token

Log in with the bot account to get an access token. You can use Element or curl:

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

Configure

Terminal window
export MUDABBIR_MATRIX_HOMESERVER="https://matrix.org"
export MUDABBIR_MATRIX_USER_ID="@bot:matrix.org"
export MUDABBIR_MATRIX_ACCESS_TOKEN="your-access-token"

Start

Terminal window
mudabbir --matrix

Configuration

SettingEnv VariableDescription
HomeserverMUDABBIR_MATRIX_HOMESERVERMatrix homeserver URL
User IDMUDABBIR_MATRIX_USER_IDBot’s Matrix user ID
Access tokenMUDABBIR_MATRIX_ACCESS_TOKENAuthentication token
Device IDMUDABBIR_MATRIX_DEVICE_IDDevice ID (auto-generated)
Allowed roomsMUDABBIR_MATRIX_ALLOWED_ROOM_IDSComma-separated room IDs
Display nameMUDABBIR_MATRIX_DISPLAY_NAMEBot display name

Features

Sync-Based

The adapter uses nio.AsyncClient.sync_forever() for real-time message delivery. No polling needed.

Edit-in-Place Streaming

Matrix supports message editing via m.replace events. Mudabbir uses this for streaming — sending an initial message and then editing it as tokens arrive.

Room Support

The bot responds to messages in any room it’s invited to. Use MUDABBIR_MATRIX_ALLOWED_ROOM_IDS to restrict access to specific rooms.

Session Keys

Each room gets a unique session: matrix:{room_id}

Installation

Terminal window
curl -fsSL https://mudabbir.fly.dev/install.sh | sh


# Or add the Matrix extra manually
pip install mudabbir[matrix]

This installs matrix-nio as an optional dependency.

Last updated: February 21, 2026
1 min read
Edit this page