Matrix Protocol: Decentralized AI Agent Access

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 POCKETPAW_MATRIX_HOMESERVER="https://matrix.org"
export POCKETPAW_MATRIX_USER_ID="@bot:matrix.org"
export POCKETPAW_MATRIX_ACCESS_TOKEN="your-access-token"

Start

Terminal window
pocketpaw --matrix

Configuration

SettingEnv VariableDescription
HomeserverPOCKETPAW_MATRIX_HOMESERVERMatrix homeserver URL
User IDPOCKETPAW_MATRIX_USER_IDBot’s Matrix user ID
Access tokenPOCKETPAW_MATRIX_ACCESS_TOKENAuthentication token
Device IDPOCKETPAW_MATRIX_DEVICE_IDDevice ID (auto-generated)
Allowed roomsPOCKETPAW_MATRIX_ALLOWED_ROOM_IDSComma-separated room IDs
Display namePOCKETPAW_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 POCKETPAW_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.

Signal Messenger

Privacy-focused messaging with end-to-end encryption via signal-cli.

Slack Bot Setup

Socket Mode integration with thread support and no public URL needed.

Docker Deployment

Run PocketPaw in Docker for easy self-hosted Matrix bot deployment.

All Channels

Compare all 9+ supported messaging platforms.

Last updated: April 29, 2026
1 min read
Edit this page