mautrix-go is a Go framework for Matrix clients and bridges

Where it sits in the Matrix ecosystem

mautrix-go is a Golang Matrix framework, and the README is quick to name who actually uses it: gomuks, go-neb, mautrix-whatsapp and others. That list is the best description of the project available, because it names three very different kinds of consumer.

gomuks is a graphical Matrix client. go-neb is a server-side bot framework. mautrix-whatsapp is a bridge that connects WhatsApp to Matrix. A library that serves a desktop client, a server-side bot and a protocol bridge is one that has to cover a lot of the protocol rather than one part of it.

The lineage matters too. The project is based on matrix-org/gomatrix, and the original project is licensed under Apache 2.0. So the starting point is the reference client library that many Go Matrix projects have used, and mautrix-go is the extended successor.

The module path is maunium.net/go/mautrix, and the documentation is at maunium.net/go/mautrix with a GoDoc badge pointing at pkg.go.dev. The module declaration in the repository reads:

module maunium.net/go/mautrix

go 1.26.0

There is also a toolchain directive pinning go1.27.2, so a build is reproducible against a specific Go release rather than whatever the local machine happens to have. That is a small detail that says the project is maintained with a modern Go toolchain in mind.

The licence is MPL-2.0, and the project is hosted at the mautrix organisation with a Matrix room for discussion at #go:maunium.net.

What the framework adds on top of gomatrix

The README states that in addition to the basic client API features the original project has, this framework also has a specific list, and it is worth reading item by item because each one is a subsystem.

Appservice support comes first, described as Intent API like mautrix-python, room state storage, etc. That is the foundation for bridges: an appservice has its own user namespace, its own device and user IDs, and it is addressed through the same Matrix API as a normal client with a different prefix.

End-to-end encryption support follows, with the parenthetical listing key backup, cross-signing and interactive verification. Cross-signing and interactive verification are the parts that are genuinely hard to get right, because they are about proving device possession to another device, and getting that subtly wrong is a security problem rather than a usability one.

Then there is a high-level module for building puppeting bridges, which is the abstraction above appservice: a bridge where the remote network's users are represented as Matrix users, with the bridge controlling their state.

The federation module is described as partial, with making requests, PDU processing and event authorization. Partial is the honest word for it, and it is the scope boundary an adopter has to understand.

The last four items are smaller helpers. A media proxy server which can be used to expose anything as a Matrix media repo. Wrapper functions for the Synapse admin API. Structs for parsing event content. Helpers for parsing and generating Matrix HTML. And helpers for handling push rules.

How the packages map to the subsystems

The top level directory listing is the clearest description of the architecture, because the package names are the subsystems.

At the root sit the client itself with client.go, requests.go and responses.go, the request and response types, room.go for room state, filter.go, sync.go and syncstore.go for the sync loop, statestore.go and the sqlstatestore/ directory for persisting sync state, oauth.go and the oauth/ directory, and error.go and url.go for the small shared types. versions.go and version.go carry the spec version handling.

The feature packages are then clearly named directories. crypto/ is the encryption stack, event/ holds the event content structs, format/ the Matrix HTML helpers, pushrules/ the push rule handling, id/ the Matrix ID parsing, federation/ the partial federation implementation, appservice/ the appservice and intent layer, bridgev2/ the high-level bridge module, mediaproxy/ the media proxy server, synapseadmin/ the Synapse admin API wrappers, and commands/ for the command handling that a bridge needs.

Two directories stand out as development infrastructure rather than library code. mockserver/ is a mock Matrix server, which is what lets the crypto and sync code be tested without a homeserver, and beeperstream/ suggests a streaming bridge integration.

The dependency list supports the same reading. golang.org/x/crypto is there for the cryptographic primitives, filippo.io/edwards25519 for the curve the Matrix specification uses, github.com/tidwall/gjson and sjson for the JSON handling on the hot path, github.com/coder/websocket for the sync connection, rs/zerolog for logging, go.mau.fi/zeroconfig for configuration and go.mau.fi/util for shared helpers, and maunium.net/go/mauflag for the command line flag handling. The database layer uses both lib/pq and mattn/go-sqlite3, so the sync store can run on PostgreSQL or SQLite.

What a first program looks like

The repository ships an example directory with a main.go, and the entry point to the library is the client. The client file at the root is client.go, and the module documentation lives at pkg.go.dev.

For a project that wants the high-level features, the pattern is to construct a client with a homeserver URL and an access token, use the crypto/ package to set up the device and the key store, and then use the sync loop with a sync store to receive events. The state store is either sqlstatestore/ for a database-backed implementation or the in-memory one.

A bridge adds the appservice and bridgev2 layers on top, and the mediaproxy/ package can sit in front to expose remote media as a Matrix media repository, which matters because a bridge that links a message to a remote image has to make that image reachable by Matrix clients.

Two things are worth checking before writing any of this. The first is the federation module, which the README calls partial, so a project that needs to receive events from arbitrary homeservers should verify that the specific federation behaviour it needs is implemented rather than assume the package is complete.

The second is the crypto setup, because end-to-end encryption in Matrix has a device identity, a key store and a verification flow, and each of those has configuration decisions that are hard to change later. A project that gets the key store wrong has a client that cannot decrypt its own history.

The example directory is the fastest way to see a working configuration, and the mock server in mockserver/ means the tests do not need a real homeserver.

Where mautrix-go fits, and where it stops

The comparison worth making is with the alternatives, and there are two real ones: writing the client API calls yourself over net/http, and using a different language entirely.

Against calling the API yourself, the difference is the volume of protocol detail. The client API is not the hard part of Matrix; the sync loop with its token and its incremental state, the room state model with its event graph and its state resolution, and the encryption stack are. A project that only needs to post a message can do that with a POST. A project that needs to be a real client, with verification and key backup, is a different scale of work, and that is the scale mautrix-go addresses.

Against a different language, the honest answer is that Matrix has a strong Go tradition, and the three named consumers are all Go, which is itself evidence. The bridge ecosystem in particular has converged on Go, and a framework that a bridge author already uses is a bridge author's default.

The limits are structural. The federation module is partial, so a project that needs to be a full server-side homeserver rather than a client or a bridge is looking at the wrong library. The sync store supports PostgreSQL and SQLite, which is a reasonable pair but not a general database story. And the whole thing is a framework rather than a product: there is no application around it, and the example is a starting point rather than something you would deploy.

There is also the MPL-2.0 licence, which is file-level copyleft rather than the per-file exception Apache 2.0 provides. The README notes that the original gomatrix project is licensed under Apache 2.0, and this project is based on it, so the licensing of the derivative is a question to check against the LICENSE file if you intend to redistribute. For most use, where the library is a dependency rather than a distributed binary, this is not an obstacle.

On maintenance the record is good. The releases are v0.32.0 from 2026-10-16, v0.31.0 from 2026-09-16 and v0.30.0 from 2026-08-16, which is a monthly minor release cadence, and the last push was on 2026-10-20 with the repository not archived.

Editorial conclusion

mautrix-go suits a Go developer writing a Matrix client, an appservice or a puppeting bridge, since it supplies the protocol layers that are tedious to implement, including end-to-end encryption, key backup, cross-signing and interactive verification, and it does so behind a stable Go API. It is the wrong tool if you only need to read a public room timeline, because the base client API is far more than that job needs. Before adopting it, read the appservice and bridgev2 documentation, check the federation module against the servers you need to talk to, because it is described as partial, and pin the version, since the module requires Go 1.26 with a 1.27.2 toolchain.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. mautrix/go on GitHub
3. Project website
4. README
5. Releases