SETUP.md

OddNet Matrix Controller Setup Guide

Prerequisites

1. A Matrix homeserver (e.g., Synapse, Dendrite, Conduit)
2. Node.js 18+ installed
3. A bot account created on your Matrix homeserver

Step 1: Create a Bot Account

Option A: Using matrix-authentication-service (recommended for modern setups)

1. Access your homeserver's admin panel
2. Create a new user account for the bot
3. Generate an access token for the bot

Option B: Using curl (traditional method)

curl -X POST "https://your-matrix-server.com/_matrix/client/r0/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "oddnet-bot",
    "password": "secure-password-here",
    "auth": {"type": "m.login.dummy"}
  }'

Step 2: Get an Access Token

Method 1: Login to get token

curl -X POST "https://your-matrix-server.com/_matrix/client/r0/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "oddnet-bot",
    "password": "your-bot-password"
  }'

The response will contain an access_token field - save this for your .env file.

Method 2: Use an existing client

1. Log in with the bot account using Element or another Matrix client
2. Go to Settings → Help & About → Advanced
3. Click "Access Token" and copy it

Step 3: Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env with your actual values:

MATRIX_SERVER=https://your-matrix-server.com
MANAGER_MATRIX_ID=@oddnet-bot:your-matrix-server.com
MANAGER_MATRIX_ACCESS_TOKEN=your_access_token_from_step2
STORAGE_PATH=./storage

Step 4: Install Dependencies

npm install

Step 5: Run the Bot

Development mode (with auto-reload):

npm run dev

Production mode:

npm run build
npm start

Step 6: Test Encrypted Messaging

1. Create a new encrypted room in your Matrix client (e.g., Element)
2. Invite the bot to the room using its full Matrix ID (e.g., @oddnet-bot:your-matrix-server.com)
3. The bot will automatically join the room
4. Send a message: !ping
5. The bot should respond with "Pong!"
6. Try: !echo Hello, encrypted world!
7. The bot should echo back: "Hello, encrypted world!"

Encryption Features

The bot is configured with:

• RustSdkCryptoStorageProvider: Handles encryption/decryption of messages
• SimpleFsStorageProvider: Persists bot state and sync tokens
• AutojoinRoomsMixin: Automatically accepts room invitations
• Message event handlers: Responds to commands in both encrypted and unencrypted rooms

Storage

The bot stores its data in the ./storage directory (configurable via STORAGE_PATH):

• storage/bot.json: Bot state and sync token
• storage/crypto/: Encryption keys and device information

Important: Keep the storage directory backed up. If you lose the crypto storage, the bot won't be able to decrypt old messages or participate in existing encrypted rooms.

Troubleshooting

Bot doesn't respond to messages

• Check that the bot successfully started (look for "Bot is ready and listening for messages!")
• Verify the bot joined the room
• Make sure messages start with ! for commands

Encryption errors

• Ensure @matrix-org/olm is installed: npm install @matrix-org/olm
• Delete and recreate the storage/crypto directory if encryption keys are corrupted
• The bot may need to re-verify with other devices in encrypted rooms

Connection issues

• Verify MATRIX_SERVER URL is correct and accessible
• Check that the ACCESS_TOKEN is valid
• Ensure your homeserver allows bot accounts

Available Commands

• !ping - Responds with "Pong!"
• !echo <message> - Echoes back the message

Next Steps

To add more commands, edit the message handler in src/main.ts (lines 49-78). The bot can now read and send messages in both encrypted and unencrypted rooms.

For more advanced features, check out the matrix-bot-sdk documentation.