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.

The connection works in both directions. Mastodon receives public posts from the relay and sends the local server's public posts to it. Saving a connection sends a subscription request; the relay must accept it before Mastodon reports the connection as Enabled.

A relay's rules and expected traffic should fit the instance being connected. Busy relays increase bandwidth, Sidekiq work, stored posts, and cached remote media. Starting with one relay makes it easier to assess the extra load before subscribing to more.

Related: How to block a Mastodon instance
Related: How to clear Mastodon media cache with tootctl

Steps to add a Mastodon relay connection:

  1. Open the Relays page at your Mastodon server's admin URL. 
    https://social.example.net/admin/relays

    The address uses your own server's domain. The signed-in account needs Manage Federation or Administrator permission.

    Relays may not work correctly with secure mode or limited federation mode enabled. A missing Relays menu item can indicate a federation-mode restriction or insufficient role permissions.

  2. Click Setup a relay connection.

    The button reads Add new relay when a connection already exists.

  3. Enter the relay's advertised Mastodon inbox URL in URL of the relay inbox. 
    https://relay.example.net/inbox

    The address comes from the chosen relay's website. Its Mastodon subscription URL may differ from the actor URL advertised for Pleroma or LitePub clients.

  4. Click Save and enable.
  5. Check that the relay's inbox URL appears in the Relays table.

    Waiting for relay's approval means the connection is saved but not yet accepted. A relay that approves subscriptions automatically may show Enabled immediately.

  6. Refresh the Relays page after subscription approval.

    If the request stays pending, the relay operator can confirm whether approval is required. Failed background delivery can also delay the request or its response.

    Related: How to monitor Mastodon Sidekiq queues

  7. Confirm that the relay's Status is Enabled.

    The relay has accepted the subscription. New relayed public posts can now reach the federated timeline; old posts are not backfilled.

    If the traffic becomes excessive, Disable stops the connection. Disabling does not remove posts or cached media already received.

Share this guide