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
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.
example-config.yaml and copy it to
<bot_dir>/config.yaml. At this point
<bot_dir> will contain
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 (
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.
admins should be configured with the username and password that will login to the bot manager page.
username needs to login with password
1234, this section will look like below
admins: username: "1234"
At this point launch the bot manager.
python -m maubot
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
- 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:
mbc auth requires you to have the server in the maubot config registration secret section
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: