Vibecoded with GLM 5.3 XMPP <-> Matrix bridge in Go
  • Go 99.7%
  • Shell 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-08 22:54:13 +00:00
.forgejo/workflows Add AGENTS.md and Forgejo CI workflow 2026-11-08 19:20:54 +00:00
cmd/mautrix-xmpp Relicense under WTFPL (public domain) 2026-11-08 19:20:54 +00:00
packaging first commit 2026-11-08 20:47:03 +03:00
pkg/connector Fetch MUC occupant avatars via occupant vCard (XEP-0045/XEP-0153) 2026-11-08 22:53:46 +00:00
.gitignore Fix reaction/reply target resolution and bridge MUC typing 2026-11-08 18:47:48 +00:00
AGENTS.md Fetch MUC occupant avatars via occupant vCard (XEP-0045/XEP-0153) 2026-11-08 22:53:46 +00:00
go.mod Add shared component login from config so all users can write 2026-11-08 19:20:25 +00:00
go.sum first commit 2026-11-08 20:47:03 +03:00
LICENSE Relicense under WTFPL (public domain) 2026-11-08 19:20:54 +00:00
README.md Always re-send Matrix reactions and harden component-mode avatars 2026-11-08 22:11:30 +00:00

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:

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_secret from 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 as matrix@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 from address 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:

  1. 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.
  2. 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-id are preferred for message IDs; the bridge falls back to the message id attribute 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_media is 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/nick in 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 with network.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 relay enabled in the bridge config and !relay set in 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.