Skip to main content

Build a Matrix AI Agent with nanoinfra

Connect nanoinfra to Matrix, on matrix.org or on a homeserver you run.

What you will build​

  • a working local nanoinfra reply
  • a Matrix account the agent answers as
  • one room where the agent replies

When to use this​

Use Matrix when you want to host the chat infrastructure yourself. Use it also when the people who should reach the agent are already on a homeserver you control.

Install​

Quick Start ranks four install methods easiest first. This is the first of them. Use pip, Docker or a source checkout instead if you prefer, and come back here.

uv tool install nanoinfra
nanoinfra onboard --wizard
nanoinfra agent -m "Hello!"

Matrix needs its optional dependency:

nanoinfra plugins enable matrix

Minimal working example​

Two ways to authenticate, and you pick one. Either a password, or an access token together with a device id:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@myagent:matrix.org",
      "password": "YOUR_PASSWORD"
    }
  }
}
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@myagent:matrix.org",
      "accessToken": "YOUR_ACCESS_TOKEN",
      "deviceId": "YOUR_DEVICE_ID"
    }
  }
}

homeserver and userId are required. homeserver defaults to https://matrix.org. Then either password, or both accessToken and deviceId — a config with neither pair complete fails to load rather than starting and failing to log in.

Start the gateway, then send the account a direct message.

It should return a pairing code. Approve that code from a trusted local surface, and not the example below:

nanoinfra agent -m "/pairing approve <the code the bot sent you>"

If you missed the code, list the pending requests:

nanoinfra agent -m "/pairing"

Access control​

groupPolicy on Matrix defaults to open, which is unusual: most channels default to mention-only. So the agent replies to every message in a room it has joined until you narrow it.

ValueBehaviour
openreply to every message in the room. The Matrix default
mentionreply only when @mentioned
allowFromreply only to listed senders

Set groupPolicy to mention for the first room, and widen it deliberately.

Production notes​

  • Prefer accessToken and deviceId over password for a long-running deployment. A token can be revoked at the homeserver without changing the account.
  • Restart the gateway after you edit config.json.

Security notes​

  • groupPolicy defaults to open. Set it to mention before you invite the account to a room with people in it.
  • Keep the account out of rooms you do not control.

Troubleshooting​

  • Run nanoinfra channels status to confirm nanoinfra sees the channel as enabled.
  • A login failure is usually a userId in the wrong form. It needs the full @user:server shape.
  • Run nanoinfra gateway --verbose while debugging channel startup.