How to Build a Topic-Specific Mastodon Relay With Tag Filter

Mastodon relays let instances share public posts with each other without following every user individually. Without a tag filter, a relay forwards all public posts from every connected instance, which can flood your local timeline with irrelevant content. Building a topic-specific relay with a tag filter solves this by forwarding only posts that contain specific hashtags, such as #photography or #tech. This article explains how to set up a Mastodon relay that filters by hashtag, covering the prerequisites, configuration steps, and common pitfalls.

What Is a Mastodon Relay and How Does Tag Filtering Work?

A Mastodon relay is a service that connects multiple Mastodon instances. When an instance subscribes to a relay, it sends all public posts from its users to the relay. The relay then redistributes those posts to all other subscribed instances. Without filtering, every public post from every connected instance appears on the local federated timeline of each subscriber.

Tag filtering limits the relay to forward only posts that include one or more specified hashtags. The relay inspects each incoming post for the presence of any tag in the filter list. If a match is found, the post is forwarded. If no match is found, the post is discarded. This mechanism requires the relay software to support server-side tag inspection. The most common implementation is Mastodon Relay version 2.0 or later, which accepts a tags query parameter in the subscription URL.

To use a topic-specific relay, you need two components: a relay server that supports tag filtering and a Mastodon instance that subscribes to that relay with the appropriate parameter. The relay does not modify the original posts. It only decides whether to forward them based on the tags present.

Prerequisites for Building a Topic-Specific Relay

Before you begin, ensure the following conditions are met:

• You have administrative access to a Mastodon instance (either your own or one where you are an admin).
• The instance runs Mastodon version 3.5 or later, which supports relay subscriptions with query parameters.
• You have access to a server where you can install the relay software. This can be a separate VPS or a Docker container on the same machine as the instance.
• The relay software must be Mastodon Relay v2.0 or a fork that implements the tags filter. The official repository is at github.com/glitch-soc/mastodon-relay.
• You have chosen the exact hashtags you want to filter. Use lowercase, no spaces. For example: photography, nature, landscape.

Steps to Set Up a Topic-Specific Mastodon Relay

The process has two main parts: installing and configuring the relay server, then subscribing your instance to it with the tag filter.

Part 1: Install and Configure the Relay Server

1. Set up the relay server software
   On your server, clone the Mastodon Relay repository and install dependencies. Run git clone https://github.com/glitch-soc/mastodon-relay.git then cd mastodon-relay and npm install. Configure the relay by editing .env with your instance domain and a secret key. For example: LOCAL_DOMAIN=relay.example.com and SECRET_KEY=your-random-secret.
2. Start the relay service
   Run npm start to launch the relay. The relay listens on port 3000 by default. Use a reverse proxy like Nginx to serve it on port 443 with HTTPS. Without HTTPS, Mastodon instances will refuse the subscription.
3. Verify the relay is reachable
   Open https://relay.example.com/api/v1/instance in a browser. You should see a JSON response with relay metadata. If the page returns an error, check the reverse proxy configuration and firewall rules.

Part 2: Subscribe Your Instance With Tag Filter

1. Log in to your Mastodon instance as an admin
   Go to https://yourinstance.com/admin/settings/relays. This is the Relays administration page. If you cannot see this page, you need admin privileges.
2. Add the relay with the tag filter parameter
   In the relay URL field, enter the full relay address followed by ?tags= and your comma-separated hashtags. For example: https://relay.example.com/?tags=photography,nature,landscape. Do not include the # symbol in the tag names. Click the Add button.
3. Approve the relay subscription
   The instance sends a subscription request to the relay. The relay must accept it. Check the relay logs by running pm2 logs if you used PM2, or journalctl -u mastodon-relay if you used systemd. Look for a line like New subscriber: yourinstance.com. If the subscription is pending, you may need to manually approve it on the relay side by sending a POST request to https://relay.example.com/api/v1/subscribers/approve with the subscriber ID. Most setups auto-approve after a few seconds.
4. Confirm the subscription is active
   Return to the Relays admin page on your instance. The relay should show a status of Active. If it shows Pending or Failed, check the relay logs and ensure your instance can reach the relay server over HTTPS.

Common Issues When Building a Topic-Specific Relay

Relay Returns 403 Forbidden When Subscribing

This usually means the relay server is configured to require authentication or the instance domain is not whitelisted. Edit the relay’s .env file and set WHITELIST_MODE=false to allow any instance to subscribe. Restart the relay after making changes. Alternatively, add your instance domain to the WHITELIST variable as a comma-separated list.

No Posts Appear After Subscription

The tag filter may be too narrow. Confirm that posts from connected instances actually contain the exact hashtags you specified. Hashtags are case-sensitive in the relay filter. Use only lowercase. Also verify that the relay is receiving posts. Check the relay logs for incoming activities. If no activities arrive, the connected instances may not be publishing public posts with those tags.

Posts With Extra Tags Get Through

The tag filter uses an OR logic. A post that contains any one of the listed tags will pass through. It cannot require all tags to be present. If you want a stricter filter, you must modify the relay source code or use a separate filtering tool. This limitation is by design to keep relay performance high.

Item	Mastodon Relay v1.0	Mastodon Relay v2.0 with Tag Filter
Tag filtering support	No	Yes
Subscription URL parameter	None	?tags=
Filter logic	N/A	OR (any matching tag passes)
Minimum Mastodon version	3.0	3.5
Relay hardware requirements	1 CPU, 512 MB RAM	1 CPU, 512 MB RAM

After completing the setup, your instance will only receive public posts that contain the hashtags you defined. This keeps the federated timeline relevant to your community. To expand the topic coverage, add more hashtags to the relay URL by editing the relay subscription in the admin panel. You can also subscribe to multiple relays with different tag sets. For advanced control, consider running a second relay instance with a different tag filter on a separate subdomain.