Running a Mastodon instance for a topic network means you want to see only relevant posts from other servers. Without a relay, your instance must manually follow each remote account or hashtag. A filtered relay automates this by receiving public posts from participating instances and forwarding only those that match your chosen keywords or hashtags. This article explains how to set up a filtered Mastodon relay using the Relay module in Mastodon 4.2 or later, configure keyword filters, and connect your instance to a topic-specific network.
Key Takeaways: Filtered Mastodon Relay Setup
- Administration > Relays > Add new relay: Creates a relay subscription that pulls public posts from selected instances.
- Filtered relay via keyword lists: Limits incoming posts to those containing specific hashtags or plaintext terms defined in the relay configuration.
- Relay invite codes: Share these with other instance admins so they can join your filtered topic network.
What a Filtered Mastodon Relay Does and Why You Need One
A standard Mastodon relay forwards every public post from every connected instance to all subscribers. This creates noise for a topic network that wants only astronomy posts or Linux discussion. A filtered relay applies a set of inclusion rules before forwarding any post. Only posts that contain at least one of the defined keywords or hashtags are sent to subscriber instances.
Mastodon 4.2 introduced built-in relay filtering through the administration panel. You define the filter as a list of terms. The relay engine checks each incoming post against that list. If no match is found, the post is dropped silently. This reduces server load and keeps the local timeline relevant for your community.
The filtered relay works at the server level. It does not replace per-user mute or block lists. Users can still filter content on their own timelines. The relay only controls what enters your instance from external servers.
Prerequisites for Running a Filtered Relay
You need Mastodon version 4.2 or higher on the instance that will host the relay. The relay is not a separate service. It is a feature of the Mastodon software itself. You must have administrator access to the instance. The instance must have the relay feature enabled in the environment configuration. Check the RELAY_ENABLED environment variable. It should be set to true in your .env.production file.
Your server should have enough storage and bandwidth to handle the expected volume of matching posts. A filtered relay with strict keywords generates far less traffic than an unfiltered relay. Still, monitor disk space and database size after enabling the relay.
Steps to Create and Configure a Filtered Relay on Your Mastodon Instance
- Enable the relay feature in your Mastodon instance
Log into your server via SSH. Open/home/mastodon/live/.env.productionwith a text editor. Add or edit the lineRELAY_ENABLED=true. Save the file. Runsystemctl restart mastodon-sidekiqandsystemctl restart mastodon-webto apply the change. - Access the relay administration page
Open your Mastodon instance in a web browser. Log in with an admin account. Navigate to Preferences > Administration > Relays. This page lists all relays your instance subscribes to and allows you to create new ones. - Add a new relay subscription
Click the Add new relay button. In the Relay URL field, enter the URL of the relay server you want to subscribe to. For a filtered relay, this URL points to the instance that defines the filter rules. Click Submit. Your instance will send a subscription request to that relay. - Define keyword filters for the relay
After the relay subscription is active, go back to the Relays page. Find your new relay in the list. Click the Filter button next to it. A text box appears where you can enter keywords or hashtags. Enter one term per line. For example, to filter for astronomy content, type#astronomy,#astrophoto,space,telescope. Click Save. - Generate invite codes for other admins
On the Relays page, click the Invite code button for your relay. A code is generated. Copy this code. Share it with administrators of other instances that want to join your topic network. They will use this code when adding your relay on their instance. - Verify that filtered posts are arriving
Wait a few minutes after setup. Check your instance’s federated timeline. You should see only posts that contain at least one of your filter terms. If you see irrelevant posts, review the filter list for missing terms or misconfigured relay settings.
Common Issues When Building a Filtered Mastodon Relay
Filtered Relay Not Forwarding Any Posts
If no posts appear on your federated timeline after setting up a filtered relay, check the filter list. Empty filter lists block all posts. The relay requires at least one keyword to forward content. Also verify that the relay server is actually receiving public posts from other instances. If the relay itself has no subscribers, it will not forward anything.
Check the Mastodon logs on the relay server. Run journalctl -u mastodon-sidekiq -n 50. Look for errors related to relay processing. A common error is a mismatched relay secret between instances. Re-generate the invite code on the relay server and share the new code with subscribers.
Relay Subscription Fails with 401 Unauthorized
A 401 error means the relay server rejected the subscription request. This happens when the invite code is expired or incorrect. Generate a fresh invite code on the relay server. Send the new code to the subscribing admin. The subscribing admin must remove the old relay entry and add a new one with the updated code.
If the issue persists, confirm that both instances are running Mastodon 4.2 or later. Older versions do not support relay filtering and may reject subscription handshakes. Upgrade both instances to the latest stable release.
Filter Terms Not Matching Expected Posts
The filter matches exact substrings in post content and hashtags. It is case-insensitive. If you filter for #linux, a post with #Linux will still match. However, a post with #linuxmint will also match because it contains the substring linux. To avoid unintended matches, use more specific hashtags like #linuxdesktop instead of #linux.
The filter does not support regular expressions or boolean operators. You cannot write #astronomy AND #mars. Each term is evaluated independently. A post matching any single term will be forwarded. If you need stricter logic, consider running a separate bot that reposts only content meeting your criteria.
Filtered Relay vs Unfiltered Relay: Performance and Content Control
| Item | Filtered Relay | Unfiltered Relay |
|---|---|---|
| Content filtering | Forwards only posts containing defined keywords or hashtags | Forwards all public posts from all connected instances |
| Server load | Lower because most posts are discarded before processing | Higher because every post must be received and stored |
| Storage usage | Lower, proportional to matching posts | Higher, proportional to total incoming posts |
| Setup complexity | Requires keyword list definition and periodic maintenance | Simple, just add relay URL and subscribe |
| Best use case | Topic-specific communities and niche networks | General-purpose instances that want broad federation |
You can now configure a filtered Mastodon relay to serve a topic-specific network. Start by enabling the relay feature on your instance. Add a relay subscription and define a keyword list that captures the relevant posts. Share the invite code with other admins to grow your network. For advanced control, consider running a separate moderation bot that applies additional rules before reposting content into your instance.