Matrix Decentralised HTTP Linking: About

Decentralised linking from the Web (HTTP contexts) to a matrix user or room.

Or, “Let’s decentralise!”

What’s this?

Matrix is supposed to be a decentralised protocol [MATRIX]. While much of it is, an important part isn’t. Matrix uses [SPEC-TO] as a centralised mechanism for linking and invitation to matrix resources from HTTP contexts.

We can do better than centralised.

This is a proposal to fix an important part of that problem.

Why Decentralise This?

Let’s call the service that provides, a reception service. Somewhat like a reception desk at a conference, it receives visitors arriving in matrix from outside, introduces them to the inside, and directs them to the room or person they are looking for.

A “default” centralised reception service ( is an anti-pattern.

A dependency on a central resource, controlled by a single entity, is a single-point-of-failure and a single-point-of-control for a big chunk of the whole matrix system.

Although the “core” protocol of matrix is decentralised, and can in principle be used independent of “”, in practice the use of “” is currently part of the system, both in theory [SPEC-TO] and in practice. It is no good arguing that the “core” protocol is decentralised if the system as a whole isn’t. A system is judged as a whole.

From a corporate stand-point, that’s Business As Usual. The corporate world is accustomed to the idea of a service provider that controls the service.

From a social “Public Goods” stand-point, that’s a defect. A protocol with a significant dependency on a single resource provided by a single provider is not decentralised.

The dependency on is an obstacle to presenting matrix as a decentralised protocol.

Avoid a single point of failure. Avoid a single point of control. Although not everyone’s priority, to some, this is essential.

Decentralised Linking and DNS

Techniques for linking to matrix resources:

The matrix: URI scheme

The matrix: URI scheme provides a way to link to matrix resources, such as matrix:user/ This is a dedicated naming scheme for matrix, and support for it is gradually being added in more contexts: matrix clients, generic web browsers, and other places.

Much as we would like to see matrix: URI scheme links supported everywhere, in web browsers and other user interfaces, however, for the foreseeable future we can only expect it will be supported in limited contexts. So this doesn’t solve the use cases in the current HTTP world.

Wide-spread linking to matrix from HTTP contexts (such as Web sites) therefore requires that we support HTTP linking.

The design

The design uses HTTP URLs like for a user id, and a similar pattern for room aliases etc. links are used in two ways: (1) the user follows the link as a generic HTTP URL, visiting the DNS domain running a web service [M.TO-SITE]; and (2) if the user’s client software is aware of matrix, it may recognise a URL as a special syntax [M.TO-SYNTAX] and parse it and invoke local matrix functionality, without visiting the DNS domain

The spec [SPEC-TO] states this scheme is intended to be used as a special syntax, as in usage (2) above. It notes, “This is not meant to be interpreted as an available web service” (original emphasis) and “Clients should not rely on URIs falling back to a web server if accessed and instead should perform some sort of action within the client.” This part of the spec seems to lack an acknowledgement that its other use as a concrete domain and service (1) is essential and wide-spread in non-matrix-aware contexts such as web browsers.


The software behind the service [M.TO-CODE] can be run on other domains: then we say it is “self-hosted”. People using a matrix client that is under their (or their administrator’s) own control can get their client to produce links to their self-hosted domain, and of course anyone can manually produce such links. Someone following such a link will arrive at the web page of the self-hosted reception service. In this way the creator of the link decides which reception service the recipient(s) will visit.

Those setting up a self-hosted reception service could even make their own matrix clients recognise such links internally. However they cannot make other people’s clients recognise such links, because there is no agreed protocol to recognise them. A seamless experience of using such links within matrix clients therefore is only possible in a closed setting such as a private federation in an organisation that controls all its clients. Outside such a constrained environment, “self-hosted” cannot provide a seamless linking experience in matrix clients. The proposed specification solves the issue of allowing arbitrary matrix clients to recognise links.

DNS naming

Matrix uses DNS-based naming for resources such as users and room-aliases (see [Scope]). DNS itself provides a natural way to route a request directly to the intended target resource. There is no need for a middle-man, no need to route the user first through a separate (central) domain before arriving at the intended domain.

As spelled out more precisely in the specification, some forms of identifier such as !room-id:domain contain a DNS domain that is not authoritative. These are out of scope — this specification does not provide any new way to deal with these kinds of identifier.

There has been some confusion about the role of the DNS domain in matrix resource identifiers, especially in the #room:domain identifier known as a room alias. In a room alias, the alias itself falls under DNS authority, while the room itself does not. In this regard, alias is a poor name for the relationship. The relationship rather is a pointer to the room.

Until now, users sharing a link to a matrix room have shared either a room-id (!room-id) or a room-alias (#room-alias:server-name-domain) and in many cases they, or their client software, have not cared to think much about distinguishing one form from the other. (TODO: MORE about this...)

In Essence: Decentralised

In essence, the proposed specification says: let each matrix server advertise its own reception service for its own resources, and recommend that clients and other tools should produce links that refer to the target server’s own reception service.

A matrix server’s own reception service provides a function broadly similar to a self-hosted ‘matrix-to’ service.

When a Matrix client displays a “link to this room” or “link to this matrix user” for the user to copy and share, the client first checks the well-known advertisement of the server-name of this room’s main alias, and constructs a URL pointing to that server’s *reception service* if it advertises one. (If not, it falls back to old behaviour: it constructs a URL pointing to another reception service it knows about such as User shares the resulting link.

When a person follows such a link in a general HTTP (Web) context, they visit the web page served by the reception service. If user has visited before and asked the reception service to remember their choice of client for opening the link, that works invisibly just like; else it will provide its own suggestions of clients that the user may like to use, and its own UI which may reflect the style and context (e.g. language) of the target.

When a person follows such a link in a context that understands decentralised matrix links, such as in a matrix-aware app, the app may resolve the link in its own way without necessarily contacting the reception service or showing the user anything. The spec defines the mechanism for this, as it already did for links.

Changes Needed

The following changes are needed to existing software and systems, in order to implement the proposed specification. should be made to redirect a DNS-MXID to the target resource’s own reception service:

The aim is that the user will see the interface and clients and options defined by the target resource rather than the “global default” interface and clients and options offered by

A secondary aim is that the user will see that the link was a ‘legacy’ style of link, and will see the ‘new’ style of link, in case they care about forwarding the link elsewhere and/or updating the source of the link.

Matrix Clients

Where a matrix client provides the user with an HTTP link to a matrix resource (DNS-MXID), and the link is available for the user to copy or share (rather than only to follow), the client should discover the target resource’s own reception service and provide a link to that if available. (If such reception service is not advertised, client may use its own choice of reception service.)

Matrix-Docker-Ansible-Deploy Playbook

Integrate support into matrix-docker-ansible-deploy.

Examples: Stories

Operator of a French matrix server configures its link end-point with French language in its URL (e.g. “à/”) and it prioritises suggestions for French-language client software.

Examples: Complaints

Q: “It’s uglier than links: now the links all start with different domains, depending on the target.”

A: Yes! Welcome to decentralisation! But note how ugliness is in the eye of the beholder. links were beautiful only for members of the happy-users club. The people who are unhappy or unable to use currently have a much worse experience: these people can create links to their own self-hosted, but matrix clients won’t recognise those links as such.

Q: “People see different landing pages depending on which matrix server the resource lives on. It breaks consistency of the Matrix on-boarding Experience.”

A: Yes! Welcome to decentralisation! That’s good, intentional, useful. Bear in mind that while the visible landing page is currently important for on-boarding, in the longer term it is a temporary inconvenience and should more and more often redirect automatically according to the user’s preference.

Q: “Every time I visit another server’s reception service, will I have to select my preferred client again?”

A: Once a client with matrix-URI support is installed and matrix-URI scheme recognised within the browser, the reception service redirects to that client without intervention for a seamless experience. For other cases... (TODO: Is there any other technique to address this, either within or outside the web browser?)

Research: Standards like Webfinger

Another aspect I wish to explore is sharing best practices with other protocols. ActivityPub/Fediverse linking is a prominent one. AFAIK they have the same problem/challenge: in general Web contexts, people often link to users or messages by posting an address of their fediverse client UI (in the matrix world, that's like linking to Can these be automatically recognised by fediverse-aware software? Well, sometimes. They're in a better position than matrix is. They use Webfinger, as described in mastodon's docs. AFAIK usage is not yet consistent across the fediverse; I'd like to study that more.

Possibly relevant also:

Terminology | References | TODO

See in the spec: matrix-decentralised-http-linking-spec


For engaging with discussion and development of the topic, please prefer the room linked here, rather than the blog comments facility:

Follow/Feedback/Contact: RSS feed · Fedi follow this blog: @julian​ · use the Cactus Comments box above · matrix me · Fedi follow me · email me · Donate: via Liberapay All posts © Julian Foad and licensed CC-BY-ND except quotes, translations, or where stated otherwise