What a DIDComm mediator is, and why an agent needs one

The problem, stated exactly

Two agents want to exchange encrypted messages. Neither is a server. Both are a wallet on a phone that is asleep, a worker that runs for ninety seconds a day, or a browser tab that is closed.

Direct delivery requires both parties online at the same instant. For software agents that is almost never true, and building around it means either (a) polling something, which needs a something, or (b) keeping an agent permanently online, which turns a wallet into a server.

A mediator is the something. It accepts messages addressed to a recipient who is not currently reachable, holds them, and hands them over when that recipient reconnects.

That is the entire job. It is the same shape as a mail server, with one difference that matters more than any other: the mediator cannot read what it carries.

What it is not

Not a message broker. A broker owns the messages it routes and typically reads them to route them. A mediator routes encrypted envelopes it cannot open.
Not push notifications. APNs or Firebase wake an app; they are not a transport for authenticated agent-to-agent messages, and they terminate at a platform vendor.
Not a directory or an identity provider. It does not vouch for anyone. It moves envelopes.
Not a Travel Rule product. Relay is transport. It does not originate, validate, or attest to anything about a message's contents. No such product exists at Solidus.

How a message actually travels

Alice's agent looks up Bob's DID document and finds a serviceEndpoint with routingKeys. Those keys say: do not deliver to Bob directly; wrap this and send it to his mediator.
Alice encrypts the message for Bob, then wraps that ciphertext in a forward message addressed to the mediator. The mediator gets an envelope inside an envelope: it can open the outer one, which says only "deliver this to routing key X", and never the inner one.
The mediator queues it against Bob's routing key.
Bob's agent comes online and asks for its mail with a delivery-request, receives the queued envelopes, and acknowledges them so the mediator can drop them.

The mechanics of steps 2 and 4 are the forward message and routing keys and the Pickup Protocol 3.0. Getting a mediator to accept mail for you in the first place is Coordinate Mediation 2.0.

See it in one command

Solidus Relay's front door is a standard out-of-band invitation, and it needs no signup:

curl -s https://relay.solidus.network/invite | jq '.body.goal_code, .services[0].serviceEndpoint.uri'
# "request-mediate"
# "https://relay.solidus.network/didcomm"

The full walkthrough is connect an agent to the mediator.

One honest detail from that response: the mediator identifies itself with a did:key, not a did:solidus. did:key is self-contained: the public key is the identifier, with nothing to resolve. It is a sound choice, and it means the mediator's own identity is not chain-anchored, whatever else Solidus anchors.

What you are trusting a mediator with

Not your message contents: those are encrypted end to end. But routing is not free of information: the mediator sees who connects, when, how often, and how big the envelopes are. That is structural, true of every mediator including ours, and it is enough to infer real things about you.

Read what a mediator can and cannot see before you route anything you care about. That page exists because "it routes envelopes it cannot read" is a true sentence that misleads people who stop reading after it.

Do you actually need one?

Often, no, and that is worth saying on our own page. If both agents are always-on services with stable public endpoints, deliver directly; a mediator adds a hop, a dependency, and a metadata observer for nothing. See when you do not need a mediator and, if you do need one, hosted vs self-hosted, running your own is sometimes the right answer.

Where Solidus Relay stands

It implements Coordinate Mediation 2.0 and Pickup Protocol 3.0, and it answers DIDComm v2 today. It has not been run against an independent DIDComm conformance suite, so "implements" is the claim, not "conformant", if strict interop with a particular vendor's agent matters, test it before you depend on it.