Matrix

PocketPaw 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 POCKETCLAW_MATRIX_HOMESERVER="https://matrix.org"
export POCKETCLAW_MATRIX_USER_ID="@bot:matrix.org"
export POCKETCLAW_MATRIX_ACCESS_TOKEN="your-access-token"

Start

Terminal window
pocketpaw --matrix

Configuration

SettingEnv VariableDescription
HomeserverPOCKETCLAW_MATRIX_HOMESERVERMatrix homeserver URL
User IDPOCKETCLAW_MATRIX_USER_IDBot’s Matrix user ID
Access tokenPOCKETCLAW_MATRIX_ACCESS_TOKENAuthentication token
Device IDPOCKETCLAW_MATRIX_DEVICE_IDDevice ID (auto-generated)
Allowed roomsPOCKETCLAW_MATRIX_ALLOWED_ROOM_IDSComma-separated room IDs
Display namePOCKETCLAW_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. PocketPaw 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 POCKETCLAW_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://pocketpaw.xyz/install.sh | sh


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

This installs matrix-nio as an optional dependency.

Last updated: February 12, 2026
Edit this page