Setting Up the Matrix Bot (Operator Guide)

Status: in progress — not yet available to users.

The code is written and the platform is wired up, but Matrix support has not been tested end-to-end in a live deployment. This guide documents the intended setup; steps may change before Matrix goes live.

MyExternalCortex connects to Matrix using matrix-nio (async Python) in long-polling mode — the same pattern as Telegram. No webhook URL or reverse proxy changes are needed for the bot itself. Users on any Matrix homeserver (matrix.org, their own, etc.) can DM the bot via federation.

Architecture Overview

User on any homeserver ──federation──▶ matrix.myexternalcortex.com (Conduit)
                                              │
                                         matrix-nio (long-poll)
                                              │
                                          bot container

The bot account lives on a Conduit homeserver you run. Federation means users don't need an account on your server — they DM the bot's Matrix ID (@aria:myexternalcortex.com) from wherever they already are.

1. Run a Conduit Homeserver

Conduit is a lightweight Matrix homeserver written in Rust. It runs on a small VM (~100–200 MB RAM, ~$6–12/month on DigitalOcean).

Recommended: run it on its own droplet separate from the bot stack to keep Matrix infra cleanly isolated.

Quick start (Docker)

# /opt/conduit/docker-compose.yml
services:
  conduit:
    image: matrixconduit/matrix-conduit:latest
    restart: unless-stopped
    ports:
      - "8448:8448"
      - "6167:6167"
    volumes:
      - ./data:/var/lib/matrix-conduit
    environment:
      CONDUIT_SERVER_NAME: matrix.myexternalcortex.com
      CONDUIT_DATABASE_BACKEND: rocksdb
      CONDUIT_ALLOW_REGISTRATION: "false"
      CONDUIT_ALLOW_FEDERATION: "true"
      CONDUIT_MAX_REQUEST_SIZE: "20000000"
      CONDUIT_TRUSTED_SERVERS: '["matrix.org"]'
      CONDUIT_LOG: "warn,rocket::launch=info,_=off,sled=off"
      CONDUIT_ADDRESS: "0.0.0.0"
      CONDUIT_PORT: "6167"

docker compose up -d

nginx for federation

Matrix federation requires a valid TLS certificate and a /.well-known/matrix/server delegation. Add to your nginx config on the Conduit VM:

server {
    listen 443 ssl;
    server_name matrix.myexternalcortex.com;

    ssl_certificate     /etc/letsencrypt/live/matrix.myexternalcortex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.myexternalcortex.com/privkey.pem;

    location /_matrix/ {
        proxy_pass http://localhost:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /.well-known/matrix/server {
        return 200 '{"m.server": "matrix.myexternalcortex.com:443"}';
        add_header Content-Type application/json;
    }

    location /.well-known/matrix/client {
        return 200 '{"m.homeserver": {"base_url": "https://matrix.myexternalcortex.com"}}';
        add_header Content-Type application/json;
        add_header Access-Control-Allow-Origin *;
    }
}

Get a certificate:

sudo certbot --nginx -d matrix.myexternalcortex.com

2. Create the Bot Account

Register the bot user via the Conduit admin API (registration is disabled for the public, but the admin can create accounts directly):

# Inside the Conduit container or using the admin token
curl -X POST https://matrix.myexternalcortex.com/_matrix/client/v3/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "aria",
    "password": "a-strong-random-password",
    "kind": "user"
  }'

Or use Element logged in as an admin user and create the account from the server admin panel.

3. Generate an Access Token

Log in as the bot user to get a persistent access token:

curl -X POST https://matrix.myexternalcortex.com/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "aria",
    "password": "a-strong-random-password"
  }'

Copy the access_token from the response. This is your MATRIX_ACCESS_TOKEN. Store the password securely (you'll only need it again if the token is revoked), then use the token for all bot operations.

4. Configure Environment Variables

Add to your .env (and set as GitLab CI/CD variables for deployment):

MATRIX_HOMESERVER_URL=https://matrix.myexternalcortex.com
MATRIX_BOT_USERNAME=@aria:myexternalcortex.com
MATRIX_ACCESS_TOKEN=your_access_token_here

Leave all three blank (or unset) to disable Matrix support — the bot starts normally without it.

5. Verify Federation

Test that other homeservers can reach yours:

# From any machine, check the federation endpoint
curl https://matrix.myexternalcortex.com/_matrix/federation/v1/version

You can also use the Matrix Federation Tester to get a detailed report on your homeserver's federation status.

6. Verify the Bot

Once the bot code is deployed with Matrix enabled:

From any Matrix client (Element, Cinny, etc.) on any homeserver, DM @aria:myexternalcortex.com
The bot should respond with the onboarding message
Send /help to see the command list

E2EE Note

End-to-end encryption (E2EE) is intentionally omitted in the first release. Messages are encrypted in transit (TLS) but not end-to-end encrypted at the Matrix layer. matrix-nio supports E2EE but it adds key-verification complexity; it will be added in a later release.

Troubleshooting

Symptom	Likely cause
Federation tester shows errors	DNS not pointing at Conduit VM, or nginx not forwarding `/_matrix/`
Bot doesn't respond to DMs	`MATRIX_ACCESS_TOKEN` invalid or expired; re-generate via the login endpoint
`M_FORBIDDEN` errors in logs	Bot account suspended, or room join failed
Users can't find the bot	Federation not working; check `/.well-known/matrix/server` returns the correct JSON
High memory usage	Conduit's RocksDB can grow with federation traffic; set `CONDUIT_MAX_CONCURRENT_REQUESTS` to limit it