Coffee Maubot 🍢 Website
Coffee Maubot 🍢
© 2024, ☕🏛

🍢Getting Started

Coffee's Maubot Plugins 🍢 is a collection of plugins for Maubot, a plugin-based Matrix bot system.

To get started, you first need to install Maubot.

Here's a quick 3-step guide for how to set up Maubot for Matrix:

Cat stretching next to laptop

Introduction

Maubot is a user-friendly bot framework designed for the Matrix messaging platform, which many people recognize as a secure and decentralized way to chat online. With Maubot, anyone can create and manage their own bots without needing to know how to code. This makes it easy to add fun and useful features to your Matrix chats, like automating tasks or connecting with other apps. Whether you want to enhance your messaging experience or streamline your online interactions, Maubot offers a simple solution that anyone can use to make the most of their Matrix conversations.

In this guide, we’ll provide a clear, step-by-step tutorial on how to selfhost and set up Maubot with your Matrix account in 2025. You’ll learn how to install Maubot, add your first bot, and customize its features -- all without needing any coding skills. We’ll also cover essential aspects of self-hosting Maubot, such as setting up encryption support and managing plugins. By the end of this guide, you'll be ready to enhance your Matrix messaging experience with your own bot. Let’s get started with this Maubot setup tutorial and explore the benefits of self-hosting!


Step 1 - Installing Maubot

Requirements: Linux; Python 3.10+ with pip and virtualenv; and a second Matrix account for your bot

  • mkdir maubot && cd maubot
  • python3.10 -m venv .
    • (Note: There is a . at the end)
  • source ./bin/activate
  • pip install --upgrade maubot[encryption]
  • mkdir plugins trash logs
  • cp example-config.yaml config.yaml && nano config.yaml
    • Update the config with your information
    • homeservers: - Skip this if your Matrix username is @####:matrix.org -- it is already added by default
    • admins: - Enter new line, add username: password, this is for the Maubot Manager Web UI login
      • Note: The login page is insecure, use an appropriate password
      • Note: Don't include ' or " in the password entry

Screenshot, config.yaml


Step 2 - Starting Maubot

To start Maubot, run:

  • python3.10 -m maubot

Then, visit the URL http://localhost:29316/_matrix/maubot to launch the Maubot Manager Web UI. Log in using your username and password, from above.

Now let's set up your second Matrix account for the bot.

Make sure only Maubot will be using this "bot account" from now on:

Get account info using Element

Note: This method will not support encrypted Matrix rooms.

Log in to Element with your second Matrix account ("bot account").

Click on the name in the top left corner, then "Settings".

Device ID:

  • Click the "Sessions" tab (left sidebar)
  • Copy your Device ID

Access Token:

  • Click the "Help & About" tab (left sidebar)
  • Scroll to the bottom and click on <click to reveal> part of Access Token
  • Copy your Access Token

Screenshot, Element Web, Sessions tab

Get account info using mbc auth (required for Encryption Support)

First, make sure your bot account's homeserver is listed above in config.yaml. (If your Matrix username is @####:matrix.org, it's included by default.)

Open a new console tab (with the previous still running):

  • cd maubot and source ./bin/activate to reactivate the venv, as needed
  • mbc login
    • First, use your Maubot Manager Web UI username and password, from above
  • mbc auth
    • Homeserver is asking for the nickname (dictionary key, not URL) from the config
      • If your Matrix username is @####:matrix.org, type matrix.org (from the config's dictionary key), not matrix-client.matrix.org
    • Username can be either the Matrix username or full Matrix user ID, that doesn't matter
    • Password is the Matrix account password
    • Note: If the command says "Registration target server not found", it means you didn't add the server to homeservers properly, or didn't enter the correct name in mbc.

In the Maubot Manager Web UI, on the left sidebar, click the + next to Clients.

Enter your Access Token and Device ID here.

Enter the word disable for Display name and Avatar URL, as needed, to prevent Maubot changing your bot's name or avatar.


Step 3 - Adding Plugins

To get started with Coffee's Maubot Plugins 🍢:

Next, from the Maubot Manager Web UI at http://localhost:29316/_matrix/maubot:

  • On the left sidebar, click the + next to Plugins
  • Drag and drop the downloaded plugin .mbp file to the ⬆️ up arrow, to upload it
    • Check that it's added to the Plugins list on the left sidebar, when done
  • On the left sidebar, click the + next to Instances
    • The ID can be any name
    • Set the Primary user (Client/bot account) and Type (plugin)

Screenshot, Maubot Manager Web UI

Your bot is now ready to use!

You can also visit the Maubot Plugins website for a full list of plugins.


Starting the Bot

In the future, you can start the bot by navigating to your maubot folder, then

  • source ./bin/activate
  • pip install --upgrade maubot[encryption]
  • python3.10 -m maubot

Then, visit the URL http://localhost:29316/_matrix/maubot to launch the Maubot Manager Web UI.


Sources: Maubot Setup, Maubot Encryption, Maubot mbc auth, Stack Exchange