How to Set Up Matrix Room Moderation with the Mjolnir Bot

Mjolnir is a Matrix moderation bot that can apply shared ban policies, redact messages, monitor protected rooms, and help moderators act without using personal accounts. A safe setup depends on three decisions: where the bot runs, who can issue commands to it, and what permissions it receives in each protected room. Keep the control room private, protect only the rooms you intend, and verify permissions before relying on the bot during an incident.

This guide follows the upstream Mjolnir setup and moderator documentation and the Matrix community moderation guidance checked on October 6, 2026. The project’s release page lists v1.12.1 as its latest release at the time of review. Check the upstream release page and configuration sample again when installing, because container tags and supported options can change.

Is Mjolnir right for your Matrix community?

Use Mjolnir when moderators need to share moderation rules across several rooms, subscribe to common policy lists, or apply repeated actions consistently. Matrix room permissions still determine what the bot can do; Mjolnir does not gain authority just because it has joined a room. For ordinary small-room moderation, built-in room tools may be sufficient. Mjolnir is most useful when the same community operates multiple rooms or needs a controlled, shared workflow.

Room moderation and homeserver administration are separate scopes. Mjolnir can manage room-level bans and redactions with appropriate room permissions. More disruptive server-wide commands—such as deactivating users, moving aliases, or shutting down rooms—require Mjolnir to be a Synapse server administrator. Do not grant homeserver admin access unless moderators have a specific need for those operations.

What should you prepare before installing it?

• A Matrix homeserver account dedicated to the bot, such as @mjolnir:example.org.
• A private management room where authorized moderators can issue commands and receive status messages.
• A persistent directory or volume for Mjolnir’s configuration and state.
• A plan for encrypted rooms. Current Mjolnir configuration supports native encryption; the configuration also documents Pantalaimon as a separate, deprecated option. Do not enable both paths together.
• A test room where you can confirm invites, permissions, and list behavior before protecting busy production rooms.

How do you install Mjolnir?

The upstream project documents Docker and self-build installation. For most administrators already running containers, Docker Compose is convenient because it can restart the bot and show logs without keeping an interactive terminal open. Follow the project’s Docker setup instructions and pin a reviewed release in production rather than relying indefinitely on a floating latest tag. The official image is matrixdotorg/mjolnir.

Prepare the configuration before starting the container. The upstream Docker guide expects the configuration under a persistent data directory at config/production.yaml. Keep that directory readable only by the administrators and service that need it. The file may contain an access token or other login credentials; do not commit it to a public repository, paste it into a support room, or include it in logs.

Use the project’s current default configuration with comments as the source of truth for option names. At a minimum, set the homeserver URL and management room, then configure authentication and encryption for your chosen deployment. If you use a token-based setup, treat the token like a password. The upstream setup guide describes obtaining it by logging in as the bot from a separate browser profile in Element and opening Settings, Help & About, and the Access token section. It warns not to log out afterward because that can invalidate the token; close that browser profile instead. For an encrypted management room, enable and test Mjolnir’s encryption support before depending on commands there.

# Illustrative values only; use the exact keys and authentication method
# from the current upstream configuration sample. Never share real secrets.
homeserverUrl: https://matrix.example.org
managementRoom: '!privateRoomId:example.org'
accessToken: '[STORE A SECRET HERE, NOT IN PUBLIC]'

That small excerpt is not a complete configuration. In particular, encryption and login settings depend on whether you use native encryption or the optional Pantalaimon path. Refer to the current sample instead of copying an old blog or compose file. The Mjolnir setup guide also recommends keeping the bot close to the homeserver network-wise to reduce response latency.

How should you secure the management room?

Create a room for trusted moderators, invite the bot account, and make the room private to the moderation team. The room ID or alias goes in managementRoom. The current configuration describes this room as the source of commands and warns that anyone who can send commands there can control Mjolnir; it does not provide a more granular per-command access-control layer. That makes membership review essential. Remove former moderators promptly and do not use the bot’s control room as a general community chat.

Encryption is recommended for the management room. If you encrypt it, verify that Mjolnir can read and respond to messages with its configured encryption method. A bot that has joined an encrypted room but cannot decrypt its events may appear online while ignoring commands. Use the upstream encryption configuration and logs to diagnose this rather than turning off room encryption as a first step.

Which permissions should Mjolnir receive?

Invite the bot to each room it should protect and give it enough room power to perform the moderation actions you expect. Matrix uses room power levels for operations such as banning, kicking, redacting other users’ events, and changing room state. The required value is defined by the room’s power-level event; Matrix defaults for ban, kick, and redaction are commonly 50 when not specified, but individual rooms can change them.

Matrix’s community guidance describes power level 100 as a common Mjolnir setup so it can enforce moderation decisions. However, that level is substantial: anyone who can control the Mjolnir account effectively has that authority in protected rooms, and the bot can become a de facto owner of them. Review each room’s power levels and choose a level that permits the bot’s required actions while limiting unnecessary authority. Do not give it homeserver administrator status for ordinary room moderation.

In Element, you can invite the bot from the room’s member panel or enter an invite command such as /invite @mjolnir:example.org. After it joins, adjust its role in the room’s member list. Repeat for every room to protect. Mjolnir cannot guard rooms it has not joined, which follows from Matrix’s decentralized, room-by-room permission model.

How do you create a ban list and add protected rooms?

Once the bot has started and posted its status in the management room, create a policy list there. Mjolnir’s upstream quick start uses this example:

!mjolnir list create COC code-of-conduct-ban-list
!mjolnir default COC
!mjolnir rooms add #community:example.org
!mjolnir verify
!mjolnir status

The first command creates a ban-list room with the shortcode COC; the person creating it is invited so they can manage its visibility. The second selects that list as the default for later moderation commands. The third adds a room to Mjolnir’s protected-room set. The verification command checks whether the bot has required permissions across protected rooms, while status helps confirm it is running as expected. Use !mjolnir help to see the command syntax available in your installed version.

Keep a policy list private if it contains internal notes or is intended only for your team. Make it public only when you want other communities to discover and subscribe to the rules. Mjolnir’s rules are additive across lists, so review watched lists before relying on them; one list can continue to match a user or server even if you remove a duplicate rule from another list.

What should you test before using it in a live incident?

• Confirm the bot posts startup and status messages in the configured management room.
• Run !mjolnir verify after inviting it to the test room and granting the chosen role.
• Run !mjolnir rooms and confirm the intended room appears, with no unrelated room included.
• Review !mjolnir protections and enable only protections you understand; automatic protections can affect legitimate users.
• Use a test account and a disposable room to validate the team’s ban, unban, and redaction procedure before applying it to real members.
• Check container logs and Mjolnir’s management-room messages if the bot misses commands or reports missing permissions.

Do not test by banning a real community member or by using a wildcard against a live server. Wildcard bans can affect many users; the current default configuration requires an extra confirmation flag for wildcard bans. Read the moderator guide before enabling automated protections, and document who can approve a high-impact action.

What are common setup mistakes?

• Giving the bot server admin for convenience: room-level moderation usually needs room power, not Synapse administrator rights.
• Leaving the management room broadly accessible: every member able to issue commands is trusted with the bot’s moderation controls.
• Forgetting protected-room permissions: a bot can be online and still fail to ban or redact if its power level is too low.
• Using encrypted rooms without configuring encryption: membership alone does not let the bot read encrypted commands.
• Copying an old setup recipe: Mjolnir’s configuration and encryption support evolve; use the current default sample and setup documentation.
• Assuming one list removal reverses every ban: another watched list may still enforce the same rule.

Where can you verify the current details?

Start with the upstream Mjolnir setup guide, moderator’s guide, and release history. For room permissions, consult the Matrix community moderation guide and the Matrix specification for room power levels. Exact installation commands and encryption settings depend on your homeserver, container setup, and Mjolnir release; these upstream references should take precedence if their instructions change.