Skip to main content

Maubot

Maubot is a plugin-based bot system for Matrix. Install plugins for various features without writing code.

Features​

  • Plugin system - Add/remove features easily
  • Web UI - Manage bots via browser
  • Multiple instances - Run many bots from one Maubot
  • Hot reload - Update plugins without restart

Installation​

docker-compose.yml
version: '3'
services:
  maubot:
    image: dock.mau.dev/maubot/maubot:latest
    restart: unless-stopped
    ports:
      - "29316:29316"
    volumes:
      - ./maubot-data:/data
docker compose up -d
# Access UI at http://localhost:29316/_matrix/maubot/

pip Installation​

pip install maubot
mbc init
mbc run

Configuration​

config.yaml
server:
  hostname: 0.0.0.0
  port: 29316
  public_url: https://maubot.example.com

database: sqlite:///maubot.db

homeservers:
  example.com:
    url: https://matrix.example.com

admins:
  admin: "your-password-hash"

Generate password hash:

mbc auth -u admin

Using the Web UI​

  1. Go to http://localhost:29316/_matrix/maubot/
  2. Login with admin credentials
  3. Clients tab → Add bot user credentials
  4. Plugins tab → Upload plugins
  5. Instances tab → Create bot instances

Utility​

PluginDescription
echoEcho messages back
diceRoll dice
reminderSet reminders
translateTranslate messages

Fun​

PluginDescription
xkcdXKCD comics
giphyGIF search
urbanUrban Dictionary

Management​

PluginDescription
welcomeWelcome new users
reactbotAuto-react
rssRSS feeds
gitlabGitLab notifications

Installing Plugins​

From Web UI​

  1. Download .mbp file from plugin repo
  2. Plugins tab → Upload
  3. Create instance with plugin

From Command Line​

# Build plugin
mbc build

# Upload to maubot
mbc upload -s http://localhost:29316 plugin.mbp

Creating an Instance​

  1. Clients → Add Matrix account for bot
  2. Instances → New Instance
  3. Select plugin, client, primary room
  4. Configure plugin settings
  5. Start instance

Writing Plugins​

Basic Plugin Structure​

from maubot import Plugin, MessageEvent
from maubot.handlers import command

class MyPlugin(Plugin):
    @command.new()
    async def hello(self, evt: MessageEvent) -> None:
        await evt.reply("Hello, World!")

Plugin Metadata​

maubot.yaml
maubot: 0.1.0
id: com.example.myplugin
version: 1.0.0
license: MIT
modules:
  - myplugin
main_class: MyPlugin

Building​

mbc build -o myplugin.mbp

Configuration for Plugins​

Plugins can have configurable settings:

from maubot import Plugin
from mautrix.util.config import BaseProxyConfig, ConfigUpdateHelper

class Config(BaseProxyConfig):
    def do_update(self, helper: ConfigUpdateHelper) -> None:
        helper.copy("greeting")

class MyPlugin(Plugin):
    async def start(self) -> None:
        self.config.load_and_update()

    @command.new()
    async def greet(self, evt: MessageEvent) -> None:
        await evt.reply(self.config["greeting"])

Resources​

Next: Mjolnir →