Your Mastodon instance is running well. Users are posting. The local timeline is active. But you want more. You want your instance to see public posts from other servers in real time, not just through slow federation. That is where a relay server comes in.
A relay server acts like a live bridge between Mastodon instances. Instead of waiting for your server to pull content from another server when someone follows a remote user, a relay pushes public posts to you as they happen. This means your federated timeline becomes a firehose of activity from any server you choose to peer with. Setting one up is not complicated, but it does require some planning and a few terminal commands.
A Mastodon relay server enables real-time cross-instance discovery by pushing public posts from one server to another. You will need a dedicated subdomain, a valid SSL certificate, and a small configuration change in your Mastodon instance. Once set up, your federated timeline will show content from peered servers as it is posted, not hours later.
What a Relay Server Actually Does
Federation in Mastodon is event driven. When a user on your instance follows someone on another server, your server requests that user’s recent posts. That works fine for individuals, but it does not help with discovery. A relay server changes the model.
A relay server subscribes to the public streams of other Mastodon servers. When those servers broadcast a new public post, the relay forwards it to all subscribed peers. Your instance receives these posts instantly and shows them in the federated timeline. This is the same mechanism that large instances like mastodon.social use to stay current with the rest of the Fediverse.
The result is a timeline that feels alive. New content appears from servers you have never interacted with before. Your users discover conversations and communities outside your instance without having to manually follow remote accounts.
Before You Start: What You Will Need
Setting up a relay server requires a few things that you likely already have if you run a Mastodon instance. Here is the checklist:
- A Linux server (Ubuntu 22.04 or Debian 12 work well)
- A domain or subdomain (relay.yourinstance.example)
- A valid SSL certificate (Let’s Encrypt is fine)
- Root or sudo access
- Mastodon already installed and running on a separate server or the same machine
If you are new to self-hosting, you might want to read up on https://getmammoth.app/how-to-launch-your-own-mastodon-server-in-2026/ first. The relay server is an add on, not a replacement for your main instance.
Step 1: Choose Your Relay Software
There are two main options for running a relay server in 2026. Both are open source and actively maintained.
| Software | Language | Setup Complexity | Best For |
|---|---|---|---|
| Mastodon Relay (ruby) | Ruby | Moderate | Admins already familiar with the Mastodon stack |
| Glitch Relay (node.js) | JavaScript | Low | Developers who prefer Node and want a lighter footprint |
I recommend starting with the Node.js version unless you have strong feelings about Ruby. It is easier to configure and uses fewer system resources.
Step 2: Set Up the Subdomain and SSL
You need a subdomain that points to the relay server’s IP address. If your relay runs on the same machine as your Mastodon instance, use a different subdomain anyway. This keeps things clean.
- Add an A record for relay.yourinstance.example pointing to your server IP.
- Wait for DNS to propagate. This usually takes a few minutes.
- Install a certificate using Certbot.
sudo apt install certbot
sudo certbot certonly --standalone -d relay.yourinstance.example
Certbot will place your certificate files in /etc/letsencrypt/live/relay.yourinstance.example/. Keep that path handy for the next step.
Step 3: Install and Configure the Relay
Clone the relay repository and install dependencies.
git clone https://github.com/mastodon/mastodon-relay.git
cd mastodon-relay
npm install
Copy the example configuration file.
cp .env.example .env
Edit the .env file with your settings. The important variables are:
DOMAIN=relay.yourinstance.example
PORT=8080
MASTODON_DOMAIN=yourinstance.example
PRIVATE_KEY_PATH=/etc/letsencrypt/live/relay.yourinstance.example/privkey.pem
CERT_PATH=/etc/letsencrypt/live/relay.yourinstance.example/fullchain.pem
The relay needs to know which Mastodon instance it is serving. It also needs the SSL key and certificate to sign requests. Without these, other servers will reject the relay’s subscriptions.
Step 4: Configure Your Mastodon Instance
Now you tell your Mastodon instance to accept the relay. This is a single line in your instance’s configuration.
Open your Mastodon .env.production file and add:
RELAY_URL=https://relay.yourinstance.example
Then restart Mastodon services.
sudo systemctl restart mastodon-web
sudo systemctl restart mastodon-sidekiq
sudo systemctl restart mastodon-streaming
Your instance will now attempt to connect to the relay on startup. If the relay is not running yet, do not worry. Mastodon will retry automatically.
Step 5: Start the Relay and Test It
Start the relay with a process manager like systemd. Create a unit file at /etc/systemd/system/mastodon-relay.service.
[Unit]
Description=Mastodon Relay Server
After=network.target
[Service]
Type=simple
User=relayuser
WorkingDirectory=/home/relayuser/mastodon-relay
ExecStart=/usr/bin/node /home/relayuser/mastodon-relay/index.js
Restart=always
[Install]
WantedBy=multi-user.target
Enable and start the service.
sudo systemctl enable mastodon-relay
sudo systemctl start mastodon-relay
Check the logs to see if the relay connected to your Mastodon instance.
sudo journalctl -u mastodon-relay -f
You should see a line that says something like “Subscribed to public timeline of yourinstance.example.” If you see errors, double check the SSL paths and the domain spelling.
Common Mistakes and How to Fix Them
Here are the pitfalls I have seen most often when people set up relay servers for the first time.
| Mistake | Symptom | Fix |
|---|---|---|
| Wrong SSL certificate path | Relay fails to start | Use absolute paths from Certbot |
| Firewall blocking port 8080 | Connection refused | Open port 8080 in ufw or iptables |
| Missing RELAY_URL in Mastodon config | No subscription | Add the line and restart services |
| DNS not propagated | SSL validation fails | Wait or use a local hosts entry for testing |
| Relay and instance on different networks | Timeout errors | Ensure both can reach each other on port 443 and 8080 |
Expert advice: If you run your relay on a separate server, make sure the Mastodon instance can reach the relay over HTTPS. Self-signed certificates will not work here. Use Let’s Encrypt or another trusted CA.
How to Peer with Other Servers
Once your relay is running, you need to tell it which servers to subscribe to. This is done through the relay’s API.
Send a POST request to your relay’s endpoint.
curl -X POST https://relay.yourinstance.example/api/v1/relay \
-H "Content-Type: application/json" \
-d '{"domain": "mastodon.social"}'
You can add as many servers as you want. Each one will push public posts to your instance in real time. Be selective. Adding every server in the Fediverse will flood your federated timeline with more content than any human can read.
Start with a handful of large, well moderated servers. You can always add more later.
What Happens When Things Go Wrong
Relays are generally stable, but they do fail sometimes. The most common issue is the relay losing its connection to a remote server. This usually happens when the remote server changes its SSL certificate or restarts.
The relay will attempt to reconnect automatically. If it does not, restart the service.
sudo systemctl restart mastodon-relay
If a specific server stops sending posts, remove it and add it again.
curl -X DELETE https://relay.yourinstance.example/api/v1/relay \
-H "Content-Type: application/json" \
-d '{"domain": "problematic.server.example"}'
Then add it back with the POST request from the previous section.
Scaling Considerations for Larger Instances
If your instance grows to thousands of active users, the relay can become a bottleneck. Each public post from a peered server is forwarded to your instance, which then redistributes it to connected clients. This adds up.
Here are a few ways to handle scale:
- Run the relay on a separate machine with its own CPU and RAM.
- Use a load balancer if you have multiple relay servers.
- Limit the number of peered servers to 10 or fewer.
- Monitor memory usage with htop or a tool like netdata.
For most small to medium instances, a single relay server on a $10 VPS will handle the load without breaking a sweat.
Putting the Relay to Work for Your Community
A relay server is a tool for discovery. It brings the wider Fediverse into your instance’s timeline. But it is only useful if your community understands what they are seeing.
Consider writing a short post explaining the federated timeline to new users. Tell them that posts from other servers appear there in real time. Encourage them to follow interesting accounts they find. This turns a technical setup into a social feature.
If you want to learn more about building engagement on your instance, check out The relay is a foundation. Community building is the structure you build on top of it.
Making Your Instance a Discovery Hub
Running a relay server transforms your Mastodon instance from an isolated island into a connected node in the Fediverse. Your users no longer have to hunt for content across different servers. It comes to them.
The setup process takes about an hour if you have your domain and SSL ready. The maintenance is minimal. In return, your instance becomes a more vibrant place where conversations flow freely across server boundaries.
Try it this weekend. Set up a relay, peer with two or three servers, and watch your federated timeline come alive. You might be surprised at how much your community grows when they can see the whole Fediverse from your little corner of it.