Skip to content

Matrix bot: Maubot on Docker

  • by

Beep, boop, I’m a bot

maubot is a bot system for Matrix, the decentralised messaging platform. The good folks in the room I hang out in have expressed a desire for a bot on occasion, so I thought I’d check it out.

While it’s described as a ‘system’, maubot can just as happily run one a single bot, if that’s what you want. Features are provided by plugins- maubot won’t do anything out of the box.

It has a Docker image, so I figured I’d use that. I followed the instructions on the Wiki page with only minor modification:

0. Create a directory (mkdir maubot) and enter it (cd maubot).

1. Pull the docker image with docker pull

2. Run the container for the first time to create a config file:

docker run --rm -v `pwd:/data:z

3. Update the config to your liking. I added a username with password in the admins section, and my homeserver in the registration_secrets section.

I then created a short docker-compose.yml file:

version: "3"
    container_name: maubot
      - /home/robert/docker-containers/maubot:/data:z
      - 29316:29316
    restart: unless-stopped
      - "traefik.http.routers.maubot.rule=Host(``)"

      name: traefik_default

And start with docker-compose up -d.

(The traefik labels make the service available via

Setting up a Bot

This gets you a management interface, but the bot itself needs to be set up. It’s not entirely obvious, though the instructions are present elsewhere in the wiki.

I manually created a user using the Riot web interface; though there are instructions on how to do it via CLI using mbc. If you go the manual route the access token that maubot asks for can be yound by clocking your avatar/username dropdown in the top left to access ‘Settings’ -> ‘Help & About’ -> ‘Access Token’:

Once done, you should have a bot:

But it won’t do anything just yet, you need to add plugins!

As an aside, I managed to run into a permissions issue at this point, where the maubot interface wasn’t responding via HTTP, and docker logs was complaining:

[2019-11-29 19:18:15,617] [INFO@maubot.init] Initializing maubot 0.1.0.dev28
[2019-11-29 19:18:15,618] [] Preloading plugins...
Traceback (most recent call last):                             
  File "/usr/lib/python3.7/", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/", line 85, in _run_code
    exec(code, run_globals)
  File "/opt/maubot/maubot/", line 58, in <module>
  File "/opt/maubot/maubot/loader/", line 270, in init
  File "/opt/maubot/maubot/loader/", line 253, in load_all
    for file in os.listdir(directory):
PermissionError: [Errno 13] Permission denied: '/data/plugins'

It’s simplest to upload the desired plugins from the web interface itself. As the wiki points out elsewhere:

To add a plugin, upload a zip file containing the maubot.yaml and relevant files at the top level. Github releases of plugins have those premade (see i.e. – file casavant.tom.poll-v1.0.0.mbp) – has a CI that makes those. Also, mbc build will make those with the relevant files.

So, for the echo plugin, go to its GitHub releases page, grab the file xyz.maubot.echo-v1.3.1.mbp and upload that to the maubot web interface by hitting the plus arrow beside ‘plugins’.

Alternatively, you can compile the plugins to a .mbp yourself: clone the main maubot repo, run to get the dependencies, then clone the plugin[s] in maubot’s directory, and finally run mbc build <plugin> for the plugin you just cloned (per mChron’s comment).

Once you have the plugins you want, create an instance for them and assign them to the bot client. That interface will also show you configuration options and let you view logs, if needed. Then you’re good to go!

Tell us what's on your mind