Mastodon relays are a feature that helps server administrators boost the flow of public posts between instances. When your instance connects to a relay, it receives public posts from every other instance connected to the same relay. This can make the federated timeline much more active without requiring thousands of individual server-to-server subscriptions. In this article, you will learn exactly what a relay does, how to set one up, and what limitations to expect.
Key Takeaways: Mastodon Relays
- Administration > Relays > Add new relay: Enter the relay server URL to subscribe your instance to a relay.
- Federated timeline population: A relay fills the federated timeline with public posts from all connected instances.
- Moderation control: Server admins can enable or disable individual relays and remove unwanted content from the federated feed.
What a Mastodon Relay Does and Why It Exists
A Mastodon relay is a middleman server that forwards public posts from one instance to many others. Without a relay, each Mastodon instance must manually discover and subscribe to every other instance it wants to follow. This process works well for small networks, but it becomes slow and incomplete as the number of instances grows. A relay solves this by acting as a hub: every instance that connects to the relay sends its public posts to the relay, and the relay sends those posts back to every connected instance.
Relays are not part of the core ActivityPub protocol. They are an optional feature implemented by Mastodon to improve content discovery. When an admin adds a relay, the Mastodon server creates a special subscription to the relay server. The relay server then pushes new public posts to the subscribing instance in near real time. The subscribing instance does not need to know about the original source instance — the relay handles the distribution.
How Relays Affect the Federated Timeline
The federated timeline, also called the local timeline in some interfaces, shows public posts from all instances that your server knows about. Without a relay, this timeline contains only posts from instances that your server has explicitly followed or that have been boosted by your local users. With a relay, the timeline fills with posts from every instance connected to that relay. This can make the timeline much more active, but it also means your server receives posts from instances you may have no direct relationship with.
Who Can Use a Relay
Only Mastodon server administrators can add or remove relays. Regular users cannot connect to a relay directly. However, users benefit from relays because they see a richer federated timeline without having to manually follow remote accounts. If you are a server admin, you control which relays your instance uses. You can add multiple relays, and you can disable any relay at any time.
Steps to Add a Relay to Your Mastodon Instance
Before adding a relay, you need the relay server URL. Public relay servers are listed on community-maintained directories. Choose a relay that is trusted and moderated. Adding an untrusted relay can flood your timeline with spam or unwanted content.
- Open the Administration panel
Log in as an admin and go to Preferences > Administration > Relays. This page shows all currently connected relays. - Enter the relay URL
Click the Add new relay button. In the text field, paste the full relay URL, for example https://relay.example.com/inbox. Click Submit. - Enable the relay
After submission, the relay appears in the list with a status of Pending. Click the Enable button next to it. Mastodon sends a subscription request to the relay server. - Wait for confirmation
The relay server must accept the subscription. This usually happens automatically within a few minutes. When accepted, the status changes to Active. Public posts from all connected instances will now appear in your federated timeline. - Verify the connection
Check your federated timeline after a few minutes. If posts from unfamiliar instances appear, the relay is working. If the timeline remains empty, the relay may be offline or the subscription failed.
Common Relay Issues and What to Avoid
Relay Stays in Pending Status
If a relay remains Pending for more than an hour, the relay server may be down or the subscription URL may be incorrect. Double-check the URL. Try removing the relay and adding it again. If the problem persists, choose a different relay server.
Federated Timeline Flooded With Unwanted Posts
A relay forwards all public posts from its connected instances. If one of those instances allows spam, your timeline will show that spam. To fix this, disable the relay in Administration > Relays. You can also block individual offending instances in Administration > Federation > Domain blocks.
Relay Causes High Server Load
Receiving posts from a relay consumes bandwidth and processing power. If your server is small, connecting to multiple large relays may slow down the server. Monitor your server resource usage after adding a relay. If the load is too high, remove the relay or use only one relay at a time.
Users Cannot See Posts From a Specific Instance
A relay only shares public posts. If an instance has strict privacy settings or blocks your instance, those posts will not appear. Also, if the relay itself has moderators who remove an instance, that instance’s posts stop flowing. In such cases, users can still manually follow individual accounts on that instance.
Mastodon Relay vs Manual Federation: Comparison
| Item | Using a Relay | Manual Federation (No Relay) |
|---|---|---|
| Setup effort | Add one URL in admin panel | No setup required; content arrives only via user follows and boosts |
| Timeline activity | High; posts from all relay-connected instances appear | Low to moderate; depends on local user activity |
| Content control | Admin can enable or disable relays; cannot filter individual posts | Admin has full control over domain blocks and instance-level moderation |
| Server resource usage | Higher bandwidth and CPU due to incoming post stream | Lower; only requested content is fetched |
| Content discovery | Users see posts from many instances without manual following | Users must actively follow remote accounts or instances |
How to Choose a Relay Server
Not all relays are equal. Some relays are run by individuals, others by organizations. Look for relays that have clear moderation policies. A relay that blocks spam and hate speech will improve your timeline quality. Check the relay’s website or contact the operator before adding it. If you run a large instance, consider hosting your own relay using software like Pub-Relay. This gives you full control over which instances can connect.
You can also test a relay temporarily. Add it, monitor your timeline for a day, and disable it if the content does not match your community standards. There is no penalty for adding and removing relays frequently.
Conclusion
You now understand what a Mastodon relay is and how it works. A relay acts as a content distribution hub that fills your federated timeline with public posts from many instances. As an admin, you can add or remove relays in Administration > Relays. For best results, choose a relay with strong moderation and monitor your server load after connecting. If you need more control, running your own relay server is a good next step.