Control your devices from anywhere.

⭐ Features • 🏡 Self Hosting • 🔌 Using Agent

Warning

Note about macOS support

This project was built mainly for my own use and has only been tested on Windows and Linux.

I do not have access to a macOS device, so the Electron app and the app itself have not been tested there. Things may not work as expected on macOS.

If you run into issues, feel free to open an issue. PRs are also welcome if you want to help improve macOS support.

⭐ Features

• Power actions for Windows, Linux, and macOS
• Wake-on-LAN support
• See which devices are online or offline in real time
• Clean and simple UI
• Lightweight Electron app for your devices
• Export or Import your data as a single Relay backup file
• And much more...!

🏡 Self Hosting

📦 Manual installation

1. Clone the project

First, download Relay and enter the project folder:

git clone https://github.com/QuintixLabs/Relay.git
cd Relay

2. Install Relay

Use one of these:

npm install

3. Start Relay

Development (auto-reload) :

npm run dev

Production:

npm start

By default, the command runs at: http://127.0.0.1:3010. You can change this by setting the PORT value in .env.

🐋 Docker

Run Relay via Docker:

Create the config folder first:

mkdir -p ./config

Then run:

docker run -d \
  --name relay \
  --network host \
  -v $(pwd)/config:/app/config \
  ghcr.io/quintixlabs/relay:latest

Or use our docker-compose.yml, which is simpler.

Run these in the same folder as your docker-compose.yml file:

mkdir -p ./config
docker compose up -d

🔓 Allow the Relay ports on your machine

After you host Relay on your machine, the next step is allowing the ports Relay needs so the Hub is reachable and Wake-on-LAN works properly.

• 3010/tcp is used for the Relay Hub

• 9/udp is used for Wake-on-LAN

Linux

If you are hosting Relay on Linux, install firewalld on your distro first.

On Arch Linux:

sudo pacman -S firewalld
sudo systemctl enable --now firewalld

Then allow the Relay ports:

sudo firewall-cmd --permanent --add-port=3010/tcp
sudo firewall-cmd --permanent --add-port=9/udp
sudo firewall-cmd --reload

⎇ Remove the ports on Linux

If you want to remove them later, run:

sudo firewall-cmd --permanent --remove-port=3010/tcp
sudo firewall-cmd --permanent --remove-port=9/udp
sudo firewall-cmd --reload

Windows

If you are hosting Relay on Windows, open PowerShell as Administrator and run:

New-NetFirewallRule -DisplayName "Relay Hub TCP 3010" -Direction Inbound -Protocol TCP -LocalPort 3010 -Action Allow
New-NetFirewallRule -DisplayName "Relay Wake UDP 9" -Direction Inbound -Protocol UDP -LocalPort 9 -Action Allow

⎇ Remove the ports on Windows

If you want to remove them later, run:

Remove-NetFirewallRule -DisplayName "Relay Hub TCP 3010"
Remove-NetFirewallRule -DisplayName "Relay Wake UDP 9"

Important

Before setting up Relay Agent, make sure the device you want to control can actually reach your Relay Hub.

If that device cannot open your Hub URL, pairing will fail

⭐ Recommended: Reach Relay Hub over Tailscale

This is the easiest and safest setup for most people.

1. Install Tailscale on the machine running Relay Hub
2. On the machine running Relay Hub, open Tailscale and copy its Tailscale IP
3. Now check that the Hub opens on that address, for example http://YOUR_HUB_TAILSCALE_IP:3010
4. If it opens, use that address in Relay Agent as your Hub URL and move to the next step

⚠️ Not Recommended: Expose Relay Hub publicly

You can also expose the Hub publicly with a domain, but we do not recommend this unless you know exactly what you are doing.

1. Expose Relay Hub with a reverse proxy, tunnel, or public HTTPS domain
2. Now, check that the Hub opens on that public address, for example https://relay.example.com
3. If it opens, use that address in Relay Agent as your Hub URL and move to the next step

🔌 Using Agent

After your Hub is running, the next step is to install Relay Agent on the device you want to control.

1. Download Relay Agent

Download the Electron app for your OS below:

OS	Download
🪟 Windows	Download
🍎 macOS	Download
🐧 Linux	Download

Important

Relay Agent listens on its local port (0.0.0.0) and can be reached through any valid network address on that machine.

That means the Hub needs a real reachable address for that device.

2. Choose how the Hub will reach the device

You have 2 main ways to do this:

⭐ Recommended: Tailscale

This is the easiest and safest setup for most people.

How it works:

1. Install Tailscale on the machine running Relay Agent
2. On the device Relay will control, open Tailscale and copy its Tailscale IP
3. Open Relay Agent on that same device, then check http://YOUR_TAILSCALE_IP:3020/health
4. If it responds, you'll use that IP in Relay Hub as the device Tailscale IP / Host when adding your first device
5. Now move on to the next step, which is adding your first device in the Hub.

⚠️ Not Recommended: Expose the device online

You can also expose the device publicly with a domain or public IP, but we do not recommend this unless you know exactly what you are doing.

How it works:

1. Open Relay Agent on the device you want to control, then check http://127.0.0.1:3020/health
2. Expose http://127.0.0.1:3020 through a tunnel, reverse proxy, or forwarded public endpoint
3. If it responds, keep the public domain or public IP from that setup ready. You'll use it in Relay Hub as the device Tailscale IP / Host.
4. Now move on to the next step, which is adding your first device in the Hub.

If you do this:

• Use HTTPS
• Secure the endpoint properly
• Understand that public exposure is riskier than Tailscale

3. Add the device in Relay Hub

Open Relay Hub in your browser and then click on the + in the top right to Add a device.

You will mainly fill in:

• Name = Choose any name you want for that device
• Space = Choose the space you want it to belong to, mainly for organizing devices
• Tailscale IP / Host = Use the reachable address you chose earlier, such as a Tailscale IP or public domain
• Agent token = Agent Token is like a password so put a password for your device
• MAC address = Optional, only needed if you want to wake that device from Relay

🖧 How to find your MAC address

Windows

Open Command Prompt or PowerShell and run:

getmac /v

Look for the active adapter and copy its Physical Address.

macOS

Open Terminal and run:

ifconfig

Look for the active network interface and copy the ether value.

Linux

Open Terminal and run:

ip link

Look for the active network interface and copy the link/ether value.

Relay Agent will sync the real OS and live port on its own after it connects.

4. Pair the device in Relay Agent

After the device exists in Relay Hub, finish pairing inside Relay Agent.

You have 2 setup options:

✍️ Set up manually

Use this if you want to type everything yourself.

Fill in:

• Hub URL = your Relay Hub address
• Agent token = the token from the device you added in Relay Hub
• Port = the local Relay Agent port, usually 3020

📄 Import config

Use this if you want a faster setup.

In Relay Hub, click the download button on that device row to download its config file, then import it in Relay Agent.

This fills the pairing details for you automatically.

5. Done

After pairing:

• Relay Agent connects to your Hub
• the Hub should show the device $\color{Green}{\textsf{Online}}$
• you can now control that device from Relay

That is the full setup ;]

📄 License

Relay is Free Software: You can use, study, share and modify it at your will. The app can be redistributed and/or modified under the terms of the GNU General Public License version 3 published by the Free Software Foundation.

↥ Scroll to top