Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Asgard offers hosted Matrix moderation bots for room admins who can't host one themselves or just want a backup for their existing bot.

Why?

Spam is always a risk in any public rooms. While you can do basic moderation like banning users directly from your client, it won't scale easily. If you have multiple rooms, you need to ban spammers from each room separately. Some clients offer a button to redact all messages when banning, but it's easy to hit rate limits when doing it with a normal account.

The benefits of moderation bots include:

  • Automatically applying policies in multiple rooms.
  • Deleting messages from banned users with less risk of hitting rate limits.
  • Subscribing to policy lists like CME (Community Moderation Effort), which can give your rooms better coverage for getting rid of spammers without needing your own 24/7 moderation team.

How?

We currently offer instances of Meowlnir and Draupnir. Both bots can follow policy lists, apply user and server bans across multiple rooms, and redact messages. Meowlnir is a newer bot that can be faster, while Draupnir has more features like automatic (optional) protections that ban users for flooding or sending an image as the first message after join.

To get started, join the #general:asgard.chat Matrix room, specify which bot you want and also include context about what rooms you're protecting (space/room link, number of rooms, number of users in rooms). After your request is approved, follow the Asgard docs for the bot you chose:

Who?

Asgard is maintained by Tulir, Sky, Cat, and Nex. The server and domain are funded by Tulir and Sky.

Meowlnir is primarily developed by Tulir and Draupnir by Gnuxie. If you use Draupnir (or even if you don't and just want to support moderation bot development), we recommend sponsoring Gnuxie on GitHub sponsors or Ko-fi.

Getting started with Draupnir

After your request for a Draupnir bot is approved, start a direct chat with @draupnir-main:asgard.chat. The bot will reject the invite and invite you to a new management room with your own Draupnir instance. The user ID of your Draupnir will be of the form @draupnir_<uuid>:asgard.chat.

After joining the management room, see the other pages under Draupnir in the sidebar for basic usage instructions. You can use !help to see a full list of commands.

If you have questions that aren't covered by the docs here or the help command, you can:

Subscribing to policy lists

Policy lists are like a shared blacklist and bots can subscribe to them. For example: A user starts spamming in room A and as a result gets added to a policy list that your bot subscribes to. Your bot will block that user from your rooms automatically.

Your Draupnir will create a personal policy list for you automatically when it is set up, however, there are more lists out there that you can "watch".

To subscribe to more policy lists, you have to write the following command in your management room:

!draupnir watch <room alias/ID>

For example, to subscribe to the community-moderation-effort (CME) list, write:

!draupnir watch #community-moderation-effort-bl:neko.dev

Community Moderation Effort (CME):

This list is maintained by the Matrix community itself and contains spammer & scammer accounts. It is trusted by many; for example the Debian and Ubuntu communities. This list is generally really fast and has an extremely low rate of false positives. Any false positives get removed as soon as managers are made aware of them.

The policy room is: #community-moderation-effort-bl:neko.dev

Codestorm auto open reg policy list (CS-open):

This list is maintained by Sky and contains ACLs for servers which have dangerously unsafe registration requirements and are therefore very likely to be used for spam attacks. This list is completely automated, both in terms of bans and unbans.

The policy room is: #cs-auto-open_reg:codestorm.net

Project Huginn and Muninn Active Threats (CAT):

This list is maintained by the matrix community itself and contains ACLs for servers which are actively used in attacks. This list is really fast and all servers are manually checked before they are added.

The policy room is: #huginn-muninn-active-threats:feline.support

Matrix.org Code of Conduct (COC):

This list is maintained by the matrix.org foundation. It is used by the foundation itself and some communities use it too. This list contains bans for all kinds of behaviour that violated the matrix.org code of conduct. This means that this list not only contain spammers but also trolls, rude people and more.

The policy room is: #matrix-org-coc-bl:matrix.org

Adding your bot to rooms

In order for your bot to be able to do anything in your rooms at all, it has to actually be in your rooms.

To tell draupnir to "protect" a room, you have to run the following command:

!draupnir rooms add <room alias/ID>

For example, if the alias of your room would be #example:example.org, then the command would look like this:

!draupnir rooms add #example:example.org

Alternatively, you can invite the bot to your room and then follow the prompts in the management room.

Giving the bot the necessary permissions

Usually, you want your bot to be able to ban people and servers in your room.
For that, the bot needs permissions to send the following events:

  • ban
  • m.room.server_acl

In Element, you can do that by opening the room settings, going to "Roles & Permissions" and then making sure that your bot has the role that is configured for "Ban users" and "Change server ACLs".

Repeat the steps for every room you want to protect.

Banning and unbanning users

Banning a user

Sometimes you will have to ban a user from your rooms manually. To do this, you have two options:

  • ban the user via your app in one of your rooms directly and then following the prompts in the management room
  • ban the user via a command to your bot in the management room

To ban a user via your bot, run the following command in your management room:

!draupnir ban <user_ID> <list> <reason>

For example, if you want to ban the user @example:example.org on your default list for the reason "spam", then the command would look like this:

!draupnir ban @example:example.org list spam

Alternatively you can also do only !draupnir ban @example:example.org and then follow the prompts in the management room.

Unbanning a user

Sometimes you will have to unban a user from your rooms because you either accidentally banned them or you decided that they deserve a second chance. To do this, you have two options:

  • unban the user via your app in one of your rooms directly and then follow the prompts in the management room
  • unban the user via a command to your bot in the management room

To unban a user via your bot, run the following command in your management room:

!draupnir unban <user_ID>

For example, if you want to unban the user @example:example.org, then the command would look like this:

!draupnir unban @example:example.org

After sending the command, simply follow the prompts in the management room.

Getting started with Meowlnir

After your request for a Meowlnir bot is approved, you'll receive an invite to the management room from your moderation bot. The user ID will be of the form @meowlnir_<uuid>:asgard.chat. The room will be unencrypted by default, but you're free to enable encryption if you want it; the bot should come with cross-signing full set up.

Once you join the room, you can use the !help command to view a full list of available commands. Refer to the Meowlnir docs for actually subscribing to policy lists and protecting rooms: https://docs.mau.fi/meowlnir/bot-config.html.

The most important command to get started is !join <id or alias> followed by !rooms protect <id or alias> to protect a room. You can also use the !bot-profile command to change the name and avatar of your bot.

The bot will be subscribed to the Community Moderation Effort (CME) and Cat's Active Threats (CAT) lists by default. You're free to unsubscribe from them, but we strongly encourage keeping them. To modify watched policy lists, you currently have to edit the fi.mau.meowlnir.watched_lists state event by hand.

If you have questions that aren't covered by the docs or the help command, you can: