- Go 99.7%
- Shell 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| cmd/mautrix-xmpp | ||
| packaging | ||
| pkg/connector | ||
| .gitignore | ||
| AGENTS.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| README.md | ||
mautrix-xmpp
A Matrix–XMPP bridge built on mautrix-go bridgev2 and mellium.im/xmpp.
The bridge supports two connection modes:
- Client mode (default): an ordinary client connection (one per logged-in Matrix user) to the user's own XMPP account. Messages, media, replies, edits, reactions, read markers and typing notifications are bridged between the two networks.
- Component mode (XEP-0114): the bridge registers on the XMPP server as an external component with its own domain — the classic deployment model for XMPP bridges, well suited for permanently bridging public rooms. See Component mode below.
Building
Requires Go 1.26+ (or any Go version matching go.mod).
go build -tags goolm -o mautrix-xmpp ./cmd/mautrix-xmpp
The goolm build tag selects the pure-Go Olm implementation, so no libolm C
library is needed. If you have libolm installed (libolm-dev) you may build
without the tag; the tag only affects Matrix-side encryption support plumbing.
Running
# Generate an example config
./mautrix-xmpp -e -c config.yaml
# Edit config.yaml (homeserver, appservice, database, logging, network: ...)
# Generate the appservice registration
./mautrix-xmpp -g -c config.yaml -r registration.yaml
# Register the registration with your homeserver, then run the bridge
./mautrix-xmpp -c config.yaml
Set up the appservice on the homeserver as described in
mau.fi/bridges/general/registering-appservices.
Postgres and SQLite are both supported through the standard database: config
section.
Logging in
After creating a management room with the bot (@xmppbot:your.domain), send
login and pick the XMPP account flow. You will be asked for:
- JID — your XMPP address (
user@example.com) - Password — your XMPP account password
- Server (optional) — a
host[:port]override if SRV records are absent
The bridge verifies the credentials by actually connecting (StartTLS or direct TLS + SASL SCRAM-SHA-1/256) before creating the login. Your login ID is your bare JID.
Note on password storage: the XMPP password (or component secret) is stored in plaintext in the bridge database (like credentials in all mautrix bridges). Protect the database with filesystem permissions or disk-level encryption.
Component mode (XEP-0114)
In component mode the bridge does not use a user account. Instead, it connects
to the server's component port and authenticates with a shared secret for a
registered component domain (e.g. xmppbridge.example.com). This is how
classic XMPP bridges and gateways are deployed, and it works without
registering any account.
Server configuration
Prosody (prosody.cfg.lua):
Component "xmppbridge.example.com"
component_secret = "CHANGE_ME_shared_secret"
The component listener listens on component_ports (default 5347). Set
component_ports = { "*" } to multiplex components on the regular client
ports instead.
ejabberd (listener section):
listen:
-
port: 5347
module: ejabberd_service
hosts:
"xmppbridge.example.com":
password: "CHANGE_ME_shared_secret"
Logging in
There are two ways to create the component login:
In the config file (recommended)
Put the credentials in the bridge config under network.component and the
bridge connects at startup by itself — no bot interaction is needed, and the
single component login serves every Matrix user:
network:
component:
jid: xmppbridge.example.com
secret: CHANGE_ME_shared_secret
# Optional:
# server: xmpp.example.com:5347 # component listener override
# home_server: example.com # service discovery domain
# bot_localpart: matrix # virtual JID localpart
Everyone in bridged portal rooms can then chat, react, show typing and send read receipts through the component (with per-user puppets in MUCs), whether or not they have their own XMPP login. If a component login with the same JID was created interactively earlier, the bridge reuses it and syncs credentials from the config.
Through the bot
In the management room, send login and pick the XMPP component flow:
- Component JID — the registered component domain (
xmppbridge.example.com) - Shared secret — the
component_secretfrom the server config - Component listener (optional) —
host[:port]of the component port (default<component JID>:5347) - Home server (optional) — XMPP domain used for service discovery (HTTP
upload etc.), usually your server's main domain (
example.com) - Bot localpart (optional) — localpart of the bridge's virtual JID
(default
matrix, i.e. the bridge acts asmatrix@xmppbridge.example.com)
The bridge verifies the secret by performing a real XEP-0114 handshake before creating the login.
What changes in component mode
- All known MUC portals are re-joined automatically on every connect — a component has no bookmark storage, so portal membership is driven purely by the bridge database. This makes it ideal for always-on public room bridges.
- Outgoing stanzas are stamped with a
fromaddress under the component domain, since the server only stamps from addresses for client connections. - Roster, bookmarks, carbons and personal MAM archives are account features and are skipped (queries to the component's own domain would loop back to the bridge).
- MUC history backfill still works through MUC MAM (the room archive is queried as a room occupant); DM history backfill does not (no personal archive).
- Media upload requires the optional home server setting to be able to discover the XEP-0363 service.
Puppets: per-Matrix-user occupants in MUCs
By default (set network.muc.disable_puppets: true to turn this off) every
Matrix user in a bridged MUC portal appears in the XMPP room as its own
virtual occupant under the component domain — the same model used by
classic gateways like Spectrum2 and biboumi:
- The puppet JID is
<mx-…>@<component domain>, derived deterministically from the Matrix user ID, so it is stable across restarts. - The room nick is the user's Matrix display name (disambiguated with a numeric suffix on conflicts) and is persisted in the portal metadata.
- Matrix room membership is mirrored to MUC presence: joining the portal room makes the puppet appear in the MUC, leaving/kick/ban removes it. This is the presence story in that direction: puppets are "online" exactly while the user is in the portal room. Puppets are also re-joined after a bridge restart.
- Messages, edits, reactions, retractions, read markers and typing from a
Matrix user are sent from that user's puppet, so XMPP participants see
separate people — no
[Name]relay prefixes. - Users without their own XMPP login do not need one: with a shared component login configured (see below), all of their events are served by the shared login automatically, and the puppet carries the identity.
- The bridge's own virtual bot (
<bot localpart>@<component domain>) stays joined as the room's technical occupant; its nick defaults to the bot localpart. Reflected stanzas from puppets are recognized and never echoed back into Matrix.
DM chats in component mode always go through the bot JID (no DM puppets).
The bridge command
!xmpp bridge <room JID> [nick] is a one-step migration helper for exactly
the "bot in both rooms" pattern:
- Run it in an ordinary Matrix room (invite the bot first). It joins the MUC on a connected login (the component login is used automatically if the command sender has no own login), creates the portal room and invites every member of the current room to it.
- Users accept the invite; as they join, their puppets appear in the XMPP room with their names.
The command cannot convert the existing room itself into a portal — the bridgev2 portal model requires portal rooms to be created and owned by the bridge — so the portal is a fresh room and the old room stays as it is.
Feature support
| Feature | Direction | Status |
|---|---|---|
| 1:1 text | both ways | supported |
| MUC text | both ways | supported |
| Media (files, images, audio, video) | XMPP → Matrix | XEP-0066 OOB / bare URLs; re-uploaded to Matrix by default, direct media through the bridge when matrix.direct_media.enabled is set (redirect to the XMPP URL, no homeserver copy), or plain link with media.reupload_to_matrix: false |
| Media | Matrix → XMPP | XEP-0363 HTTP upload + OOB; with media.direct_media: true a signed public URL served by the bridge is preferred instead (XEP-0363 remains the fallback) |
| Replies | both ways | XEP-0461 with fallback-body stripping |
| Edits | both ways | XEP-0308 |
| Message retraction | both ways | XEP-0424, XEP-0425 moderation is treated as a removal |
| Reactions | both ways | XEP-0444 (unicode emoji) |
| Read receipts | both ways | XEP-0333 displayed markers |
| Typing | both ways | XEP-0085 chat states |
| Carbons | server → bridge | XEP-0280, messages from your other XMPP clients appear in Matrix |
| History backfill | XMPP → Matrix | XEP-0313 MAM: initial backfill on portal creation and catch-up after downtime, using the server-assigned stanza-id as cursor |
| Avatars / names | XMPP → Matrix | XEP-0084 PEP avatars + XEP-0054 vCard-temp + roster names, with in-memory caching; MUC rooms expose their vCard photo as the portal avatar |
| Avatars / names | Matrix → XMPP | XEP-0054 vCard served by the component for the bot and every puppet JID (component mode), with XEP-0153 vcard-temp:x:update photo-hash presence so clients re-fetch |
| Room subject | XMPP → Matrix | MUC subject → Matrix topic |
| Bookmarks | server → bridge | XEP-0402 with XEP-0048 private storage fallback, auto-join |
Media routing
Matrix → XMPP: by default the bridge downloads the file from the Matrix
homeserver (decrypting E2EE attachments) and uploads it to the user's own XMPP
server via XEP-0363, advertising the download URL with XEP-0066 OOB. If the
XMPP server has no upload service (or media.upload_to_xmpp is disabled), the
bridge falls back to a signed public media URL served by the bridge itself
(matrix.public_media.*); XMPP clients can always fetch media that way as long
as the bridge's appservice address is reachable.
With media.direct_media: true the order is reversed: the signed public URL
becomes the primary link and XEP-0363 is the fallback — no file copy is made
on the XMPP server.
XMPP → Matrix: by default the file is downloaded from the XMPP URL and
re-uploaded to the Matrix media repository. With direct_media.enabled in the
matrix config section, the bridge instead hands out an mxc:// URI backed by
its own direct media server and redirects Matrix clients to the original XMPP
URL on download — the media bytes never touch the homeserver.
XMPP avatars and names are looked up per ghost at first contact and cached; avatars are fetched from XEP-0084 (PEP, the modern mechanism used by Conversations et al.) with a XEP-0054 vCard photo fallback. Failed lookups are retried after a TTL so users without avatars do not generate per-message IQs.
Avatars in MUCs require a non-anonymous room. XMPP clients fetch a room
occupant's vCard (or PEP avatar) only when they know the occupant's real JID,
and the bridge can only do the same. In the default semi-anonymous MUC
configuration real JIDs are hidden, so avatars for MUC participants cannot
work in either direction — enable "Show real JIDs to everybody"
(muc#roomconfig_publicroom, Conversations: room details → "Non-anonymous",
Gajim: room config → "Present real JIDs to all") on each bridged room. DM
avatars work regardless of this setting. Matrix → XMPP additionally needs the
XMPP client to be able to reach the component domain to fetch the puppet
vCards, which is always the case for participants of federated rooms.
XEPs used
XEP-0030, XEP-0045, XEP-0048, XEP-0054, XEP-0066, XEP-0084, XEP-0085, XEP-0114, XEP-0153, XEP-0199, XEP-0280, XEP-0308, XEP-0313, XEP-0333, XEP-0359, XEP-0363, XEP-0402, XEP-0424, XEP-0425, XEP-0444, XEP-0461, XEP-0393 (formatting conversion).
Graceful degradation
Modern server features are used when available and skipped otherwise:
- XEP-0359 stable IDs:
origin-id/stanza-idare preferred for message IDs; the bridge falls back to the messageidattribute on servers without support (IDs are then only stable for the current server run). - XEP-0363 upload: if the server has no upload service, Matrix media is
shared as a signed public URL served by the bridge when
matrix.public_mediais enabled, and as a plain text link otherwise. - XEP-0084 avatars: users without a PEP avatar fall back to their XEP-0054 vCard photo; users without either get no avatar.
- XEP-0313 MAM: without MAM there is no history backfill or offline catch-up; live bridging keeps working.
Design notes
Portal and ghost model
- DM portals are per-login (
PortalKey.Receiver= login JID), because the same contact may be reached from several accounts. - MUC portals are shared (empty
Receiver): one Matrix room per MUC for all bridge users, WhatsApp-group style. Every user's own client joins the MUC with its own account; Matrix messages are sent through the sending user's own login. - Ghosts map to bare JIDs. MUC occupants map to their real bare JID when
the room is non-anonymous (status 100/210), and to
room@service/nickin anonymous rooms. Ghosts join portals when first seen and never leave due to XMPP presence — membership is decoupled from presence to avoid leave/rejoin churn. Occupant leaves can optionally be bridged withnetwork.muc.bridge_leave_events: true.
Presence
Matrix (as of bridgev2) does not propagate presence to appservice bridges, and
bridgev2 exposes no ghost presence mechanism (verified against the current
mautrix-go source). Presence bridging is therefore intentionally limited to
sending available presence on connect (network.presence.send_available).
This was an explicit plan fallback decision.
Message ID scheme
| Concept | Mapping |
|---|---|
| Portal (DM) | contact bare JID, Receiver = login |
| Portal (MUC) | room bare JID, shared |
| Ghost (DM contact) | bare JID |
| Ghost (MUC occupant) | real bare JID if non-anonymous, else room@service/nick |
| Message | oid:<origin-id> / sid:<stanza-id> / id:<id attr> in that priority |
Outgoing messages always set origin-id (and id to the same value), so
self-messages delivered via carbons or MUC reflection are deduplicated against
the stored Matrix messages by the central bridge.
For MUC messages, XEP-0444 reactions, XEP-0308 edits and XEP-0333 markers referencing the room-assigned ID of the bridge's own outgoing messages are resolved via an in-memory mapping built from the room reflections; references to those messages are dropped after a bridge restart (best effort, logged).
Bot commands
| Command | Description |
|---|---|
join-muc <room JID> [nick] |
Join a MUC |
leave-muc |
Leave the MUC bridged to the current room |
list-rooms |
List MUCs the client has joined |
set-nick <nick> |
Change your nick in the current MUC |
bridge <room JID> [nick] |
Bridge a MUC: create a portal room and invite everyone from the current room |
The generic bridgev2 commands (login, logout, start-chat <jid>,
resolve-identifier <jid>, provisioning API endpoints, etc.) all work through
the standard bridgev2 machinery.
Metrics and monitoring
mxmain ships a Prometheus exporter and health endpoint. Add to config.yaml:
metrics:
enabled: true
listen: 127.0.0.1:8001
GET http://127.0.0.1:8001/metrics— Prometheus metrics (Go runtime, Matrix client, and appservice metrics).GET http://127.0.0.1:8001/health— returns the bridge state including per-login states (used by systemd/OpenRC health checks or uptime probes).
Connection problems are surfaced through the standard bridge state mechanism:
CONNECTED, CONNECTING, TRANSIENT_DISCONNECT (with xmpp-connect-error /
xmpp-tls-error) and BAD_CREDENTIALS (with xmpp-auth-failed).
Packaging
packaging/openrc/mautrix-xmpp and packaging/dinit/mautrix-xmpp contain
service files for OpenRC and dinit. Copy them to
/etc/init.d/mautrix-xmpp / /etc/dinit.d/mautrix-xmpp respectively,
adjust the user/paths, then:
# OpenRC
rc-update add mautrix-xmpp default
rc-service mautrix-xmpp start
# dinit
dinitctl enable mautrix-xmpp
Encryption
- Matrix-side E2EE is a bridgev2 feature (the
encryption:config section). It is treated as optional; test carefully before enabling. - XMPP-side OMEMO is not supported. Messages in OMEMO-encrypted MUCs will
not appear (they arrive as encrypted bodies or not at all).
aesgcm://OOB links are not supported.
Known limitations
- No XEP-0198 stream management (mellium.im/xmpp does not implement it); reconnects use exponential backoff plus MAM catch-up instead.
- Client mode has no relay-bot style virtual accounts: Matrix users either
bridge through their own XMPP account or (with
relayenabled in the bridge config and!relay setin the portal) through a designated relay login with name prefixes. Per-user puppets are only available in component mode. - Puppet presence follows Matrix room membership only; Matrix does not propagate online/away states to appservice bridges, so puppets show as available while the user is in the portal room.
- Matrix → XMPP avatars are only available in component mode: the bridge can serve vCards for the JIDs under its own component domain. In client mode the XMPP server answers vCard queries for accounts, and the bridge cannot speak for other users.
- Matrix → XMPP avatars are only refreshed when a puppet (re)joins or a vCard is requested after the cache TTL; Matrix display name changes propagate on the next puppet join.
- Component mode has no roster, bookmarks, carbons or personal archive; DM portals work live but DM history backfill is not available.
- XMPP presence, subscription requests (XEP-0077/RFC 6121 rosters subs) and ad-hoc commands are not bridged.
- XHTML-IM (XEP-0071) is not parsed for incoming formatting; XEP-0393 styling is converted instead.
- No outgoing stanza rate limiter beyond the bridgev2 backfill queue pacing.
- Matrix → XMPP reactions send a single-element reactions set (XMPP clients treating the set as complete will replace that user's previous reactions).
Testing the XMPP side
Local stack recommendation: Prosody or ejabberd with mam, carbons, muc,
http_upload (mod_http_upload / mod_http_upload_external) enabled, plus
clients Conversations, Dino and Gajim — their XEP support differs, so check
each feature against more than one client.
Scenarios worth testing: reconnect during traffic (catch-up dedup), duplicate delivery after carbons, edit/retract of old messages, nick change in a MUC, large files both ways, and a server without an upload service.
License
This project is released into the public domain via the WTFPL: you just DO
WHAT THE FUCK YOU WANT TO. See the LICENSE file. There are no copyright
holders to credit — the code was written with AI assistance.