Preparation
In order to create a bot from a basic configuration, clone this repository.
Cloning is only required to reuse some necessary configuration files. It is not necessary to clone the repository
in order to install maubot.
This can be done via pip install maubot.
From now on we refer to the directory where this repository has been cloned to as maubot.
The new bot will have its own directory, which can be created anywhere on the local filesystem with
mkdir <bot_dir> where <bot_dir> is a name of your choice.
Copy maubot/example-config.yaml to <bot_dir>.
Keep file example-config.yaml and copy it to <bot_dir>/config.yaml. At this point <bot_dir> will contain
both example-config.yaml and config.yaml.
In the same directory <bot_dir> create three directories that will be used by the bot later. Type
cd <bot_dir>
mkdir logs plugins trash
Before running the bot, edit config.yaml in all its sections.
In particular in section plugin_directories make sure that the bot will use the directories created before (./trash and ./plugins).
Section server is self explanatory in its default.
Make sure it looks like below
server:
# The IP and port to listen to.
hostname: 0.0.0.0
port: 29316
In any case, use the same port when you will point the browser later.
Section admins should be configured with the username and password that will login to the bot manager page.
If username needs to login with password 1234, this section will look like below
admins:
username: "1234"
At this point launch the bot manager.
From directory <bot_dir> launch
python -m maubot
Usage
Point the browser to http://localhost:29316/_matrix/maubot/#/login. After login, continue with
- adding a plugin,
- adding a client
- and finally add an instance of a bot
Adding a plugin
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. https://github.com/TomCasavant/PollMaubot/releases - file casavant.tom.poll-v1.0.0.mbp) - mau.dev/maubot has a CI that makes those. Also, mbc build will make those with the relevant files.
Adding a client
Once you added at least one plugin, you need to create a client too. To create the client and obtain the access token for the client, you need to use the mbc binary. If you use the docker-container this will not be available, therefor you have to use the python-module with docker exec -it maubot /usr/bin/python3 -m maubot.cli.
- log into the maubot server first with:
mbc login(to login use account specified in maubot's config.yaml) - register a new account for the bot on your HS with:
mbc auth --register - copy the
Access tokeninto the administration web interface
The binary interface will look something like this:
NOTE: mbc auth requires you to have the server in the maubot config registration secret section
If you have a Matrix account already created, you can also use mbc auth without the --register command to simply log in as that account and generate a session token. This method makes it possible to use accounts on a homeserver which you do not control, or otherwise do not have access to the shared registration secret (e.g. a matrix.org account).
Adding a (bot) instance
Finally, in the instance view, create an instance. Choose a client and a plugin via the screen like the one below:
Encryption Support
In order for Maubot to work in encrypted rooms, take note of the device_id returned by logging in with mbc auth. You can also fetch the device_id for an existing session through use of the matrix APIs, which are outside the scope of this document. The device_id must match the session that Maubot is using, otherwise the bot will not work properly in encrypted rooms.
Within your Maubot database, set the device_id value in the client table to the appropriate device_id for the respective bot client. Your Maubot should now be able to send and receive encryption keys! If you're still having trouble, it is probably worth restarting Maubot to pick up the changes.
NOTE: In encrypted rooms, Maubot may have issues keeping track of who to share encryption keys with, particularly new members. See https://github.com/maubot/maubot/issues/108 for a workaround until this is resolved.