If you run a Mastodon server, you may notice that your local timeline feels quiet or that users complain about seeing only posts from their own instance. A Mastodon relay is a server that forwards public posts from all connected instances to every other connected instance, filling your federated timeline with diverse content. Without a relay, your instance only receives posts from users who are directly followed or from servers that someone on your instance has searched for. This article explains what a relay does, how to subscribe to one from the Mastodon admin panel, and what to watch out for after connecting.
Key Takeaways: Subscribing to a Mastodon Relay
- Administration > Relays > Add new relay: The exact path in the Mastodon admin panel to enter a relay server URL.
- Relay URL format: Must be the root address of the relay server, for example
https://relay.example.com, without a trailing path. - Relay status indicators: After subscribing, check if the relay shows “Enabled” or “Pending” — a pending status means the relay operator must approve your instance first.
What Is a Mastodon Relay and How Does It Work?
A Mastodon relay is a dedicated server that aggregates public posts from many Mastodon instances and redistributes those posts to every other instance connected to the relay. When your instance subscribes to a relay, your server sends its own public posts to the relay server. In return, the relay sends your server the public posts from every other instance that is also subscribed to that relay.
This mechanism is fundamentally different from how Mastodon normally discovers content. Without a relay, your instance learns about another server only when one of your users follows an account on that remote server or when a remote user follows someone on your instance. This is called “pull-based” federation. A relay changes this to a “push-based” model: the relay pushes content from all member servers to all other member servers automatically.
The relay does not store posts permanently. It acts as a real-time forwarding service. When a post arrives from one instance, the relay immediately sends it to every other connected instance. If your instance goes offline temporarily, the relay does not queue missed posts. Once your instance reconnects, it will only receive new posts from that point onward.
Before subscribing to a relay, you need two things. First, ensure your Mastodon instance is running version 3.0 or later because relay support was introduced in that version. Second, obtain the URL of a relay server that you trust. Public relay lists exist, but you should verify that the relay operator has a good reputation and does not forward spam or abusive content. Joining an untrusted relay can flood your instance with unwanted posts.
Steps to Subscribe to a Mastodon Relay From the Admin Panel
The following steps assume you have administrator access to your Mastodon instance. You must be logged in with an account that has the Admin role or a custom role with the manage_relays permission.
- Open the Administration menu
In the Mastodon web interface, click the hamburger menu icon (three horizontal lines) in the upper-left corner of the screen. From the menu that appears, click Preferences. On the Preferences page, locate and click Administration in the left sidebar. If you do not see this option, your account does not have admin privileges. - Navigate to the Relays page
Under the Administration section, click Relays. This opens the relay management page. The page displays a list of all relays your instance is currently subscribed to, along with their status. If this is your first relay, the list will be empty. - Click the “Add new relay” button
Near the top of the Relays page, click the button labeled Add new relay. A text input field and a submit button appear. - Enter the relay server URL
In the text input field, type the full URL of the relay server. The URL must begin withhttps://and should not include any path after the domain. For example, if the relay is athttps://relay.mastodon.example, type exactly that. Do not add/inboxor/api— the Mastodon software appends the correct endpoints automatically. Click Submit after entering the URL. - Wait for the relay status to update
After submitting, the relay appears in the list with a status. The status can be Pending, Enabled, or Disabled. A Pending status means the relay operator must approve your instance before posts start flowing. An Enabled status means the connection is active and posts are being exchanged. A Disabled status means the relay has rejected your subscription or has been manually turned off. Refresh the page after a few minutes to see if the status changes. - Verify that posts are arriving
Check your federated timeline (the “Federated” column in the web interface) after 10 to 15 minutes. If the relay is working, you should see public posts from instances you have never interacted with before. If you see no new posts, the relay may be idle, or your instance may not have any public posts to send in return.
Common Pitfalls and Limitations When Using a Mastodon Relay
The relay status stays “Pending” for hours
This is the most common issue. A relay operator must manually approve each instance that requests a subscription. Some relay operators are slow to respond or have stopped maintaining their relay. If the status remains “Pending” for more than 24 hours, try a different relay. You can remove the pending relay by clicking the delete icon next to it in the relay list, then subscribe to another relay.
The relay shows “Disabled” immediately after subscribing
A “Disabled” status usually means the relay operator has blocked your instance. This can happen if your instance has a reputation for hosting spam, if your server is running an outdated Mastodon version, or if the relay operator has a closed membership policy. Check your instance’s federation health by looking at the Administration > Federation page. If your instance is listed as “Suspended” on many servers, consider moderating your users before trying again.
The federated timeline is still empty after the relay is enabled
Even with an enabled relay, your federated timeline may appear empty if no connected instance is posting publicly. Relays only forward public posts from instances that are actively posting. If all instances in the relay are quiet, you will see nothing. Additionally, your instance must have at least one public post to send to the relay. If your users only post to unlisted or followers-only visibility, the relay has nothing to forward. Ask your users to make at least some of their posts public to keep the relay active.
Performance issues after joining a large relay
A large relay with hundreds of instances can send thousands of posts per minute to your server. If your server has limited CPU, RAM, or bandwidth, this flood can cause the web interface to slow down or even crash the Sidekiq worker processes. Monitor your server’s resource usage after connecting to a relay. If performance degrades, consider unsubscribing from the relay or switching to a smaller, curated relay that limits membership.
Mastodon Relay vs Direct Federation
| Item | Mastodon Relay | Direct Federation |
|---|---|---|
| Content discovery | Push-based: relay sends all public posts from all members to your instance | Pull-based: your instance only learns about a remote server when a user follows someone on it |
| Setup effort | One-time subscription via admin panel | No setup required; happens automatically as users follow remote accounts |
| Control over content | Low: you receive everything from all relay members unless you use domain blocks | High: you only receive content from servers that your users explicitly interact with |
| Server load | High: constant stream of incoming posts from many servers | Low: only receives posts from servers your users follow |
| Best for | Instances that want a busy, diverse federated timeline quickly | Instances that prioritize low resource usage or strict content moderation |
After subscribing to a relay, you can manage the connection from the same Administration > Relays page. You can disable a relay without deleting it by clicking the toggle switch next to it. Disabling stops all incoming and outgoing relay traffic. Deleting the relay removes it from your instance entirely and stops all communication with that relay server.
If you want to fine-tune which content from a relay reaches your users, use the Administration > Federation > Domain blocks page to block specific domains that are part of the relay. Domain blocks override relay subscriptions, so posts from a blocked domain will not appear on your instance even if they are forwarded by the relay.
Consider starting with a small, moderated relay that has fewer than 50 instances. This gives you a chance to observe how the relay affects your server performance and content quality before committing to a larger relay. You can always add more relays later from the same admin panel.