How to add a Mastodon relay

Mastodon relays exchange public posts between servers that choose to subscribe to the same relay. They are most useful for small or new instances whose local users have not yet followed enough remote accounts to make the federated timeline active.

Mastodon subscribes to a relay from the admin relays page by sending a signed Follow activity to the relay inbox URL. The local relay row starts as Waiting for relay's approval and becomes Enabled only after the relay sends an Accept activity back to the server.

Use a relay that publishes a Mastodon-compatible inbox URL and accepts the kind of server being connected. Relays can add traffic, Sidekiq work, stored statuses, and cached remote media, so start with one relay and check the operational impact before adding more.

1. Confirm that the signed-in admin role can manage federation.

   The Manage Federation permission controls the relays page. The Administrator permission also has access because it bypasses individual role permissions.

2. Copy the relay's Mastodon inbox URL.

   https://relay.example.net/inbox

   Use the relay URL advertised for Mastodon subscriptions. Do not use a LitePub or Pleroma actor URL unless the relay operator explicitly says it is also the Mastodon inbox URL.

3. Open the Mastodon relays page.

   https://social.example.com/admin/relays

   Mastodon warns that relays may not work correctly while secure mode or limited federation mode is enabled. If the Relays menu item is missing, check federation mode and the admin role permissions before adding the relay.

4. Click Setup a relay connection or Add new relay.
5. Paste the relay inbox URL into Relay URL.
6. Click Save and enable.
7. Check the new relay row in the Relays table.

   The first status is usually Waiting for relay's approval. Leave the row in place until the remote relay accepts or rejects the subscription.

8. Verify that the relay status changes to Enabled.

   $ RAILS_ENV=production bin/rails runner 'puts Relay.accepted.pluck(:inbox_url)'
   https://relay.example.net/inbox

   Run the command from the Mastodon application directory, or from the web container for a Docker deployment. The web table is the primary check; the read-only query is useful when a change ticket needs a shell transcript.

9. Open the federated timeline from a local account after the relay is enabled.

   Relays do not backfill old posts. New public posts from the relay should appear only after the subscription is accepted and Sidekiq can process incoming ActivityPub delivery.
   Related: How to monitor Mastodon Sidekiq queues