Everything you need to set it up, open the right ports, run it and fix it when something doesn't work. Tap Copy next to any command to copy it.

How it works

Your phone (or OBS) sends video to this server. The server picks the input you want on air, shows a Be-right-back screen if the signal drops, turns it into one steady program, and sends that program to each platform you add (Twitch, YouTube, Kick…). Viewers never see your signal wobble, because the program carries on.

The program is encoded once and every destination just copies it, so extra destinations cost almost no CPU. The flip side: by default every destination gets the same picture. With a Pro licence you can pick one input for a single destination (in its row on the Live tab); that costs one extra encoder.

The dashboard is split into tabs: Live (inputs, destinations, recording), Stats, On-screen (Be-right-back and Starting-soon screens, clips, picture-in-picture, overlay), Automation (backup switching, auto-start/stop, chat commands, Discord, the cwtch.es remote) and Settings (picture quality, ports, licence, updates, backup).

Set up on your system

IRL Relay runs in Docker, and the steps depend on what the computer behind it runs. Pick yours and this section shows everything for it: install, finding the control page, everyday commands, updating, firewall, Tailscale and WireGuard, the graphics card, and OBS inside the relay. Your choice is remembered on this device.

cd /mnt/user/appdata && unzip irl-relay-*.zip

cd /mnt/user/appdata/irl-relay && docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -v /mnt/user/appdata/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

curl -s http://localhost:8780/api/ping

hostname -I

docker inspect irl-relay | grep CONTROL

docker rm -f irl-relay

docker logs irl-relay | grep -i password

docker exec -it irl-relay sh

docker stats irl-relay

cp -r /mnt/user/appdata/irl-relay-data /mnt/user/appdata/irl-relay-data-backup

-e LICENSE_KEY=IRL1.xxxxx.yyyyy

docker rm -f irl-relay
cd /mnt/user/appdata/irl-relay && docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=GPU-your-uuid-here -e NVIDIA_DRIVER_CAPABILITIES=all -v /mnt/user/appdata/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

ls /dev/dri

cd /mnt/user/appdata/irl-relay && docker build --build-arg WITH_GPU=1 -t irl-relay .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --device /dev/dri -v /mnt/user/appdata/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

cd /mnt/user/appdata/irl-relay && docker build --build-arg WITH_OBS=1 -t irl-relay-obs .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -p 6080:6080 -v /mnt/user/appdata/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay-obs

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

sudo apt install -y unzip curl
curl -LO https://cwtch.es/downloads/irl-relay-1.13.zip
unzip irl-relay-*.zip -d "$HOME"
mkdir -p "$HOME/irl-relay-data"

cd $HOME/irl-relay && docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -v $HOME/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

hostname -I

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

curl -s http://localhost:8780/api/ping

hostname -I

docker inspect irl-relay | grep CONTROL

docker rm -f irl-relay

docker logs irl-relay | grep -i password

docker exec -it irl-relay sh

docker stats irl-relay

cp -r $HOME/irl-relay-data $HOME/irl-relay-data-backup

-e LICENSE_KEY=IRL1.xxxxx.yyyyy

docker rm -f irl-relay
cd $HOME/irl-relay && docker build -t irl-relay .

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

sudo apt install wireguard
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

sudo ubuntu-drivers install && sudo reboot

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list && sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker

docker run --rm --gpus all debian:bookworm-slim nvidia-smi

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --gpus all -v $HOME/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

ls /dev/dri

cd $HOME/irl-relay && docker build --build-arg WITH_GPU=1 -t irl-relay .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --device /dev/dri -v $HOME/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

cd $HOME/irl-relay && docker build --build-arg WITH_OBS=1 -t irl-relay-obs .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -p 6080:6080 -v $HOME/irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay-obs

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

sudo pacman -S docker unzip curl
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

sudo zypper install docker unzip curl
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

curl -LO https://cwtch.es/downloads/irl-relay-1.13.zip
unzip irl-relay-*.zip -d "$HOME"
mkdir -p "$HOME/irl-relay-data"

cd $HOME/irl-relay && docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -v $HOME/irl-relay-data:Z:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

hostname -I

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

curl -s http://localhost:8780/api/ping

hostname -I

docker inspect irl-relay | grep CONTROL

docker rm -f irl-relay

docker logs irl-relay | grep -i password

docker exec -it irl-relay sh

docker stats irl-relay

cp -r $HOME/irl-relay-data $HOME/irl-relay-data-backup

-e LICENSE_KEY=IRL1.xxxxx.yyyyy

docker rm -f irl-relay
cd $HOME/irl-relay && docker build -t irl-relay .

sudo firewall-cmd --permanent --add-port=8780/tcp --add-port=1935/tcp --add-port=8890/udp && sudo firewall-cmd --reload

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

sudo dnf install wireguard-tools
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

sudo pacman -S wireguard-tools
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo && sudo dnf install -y nvidia-container-toolkit

sudo pacman -S nvidia nvidia-utils nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker

docker run --rm --gpus all debian:bookworm-slim nvidia-smi

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --gpus all -v $HOME/irl-relay-data:Z:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

ls /dev/dri

cd $HOME/irl-relay && docker build --build-arg WITH_GPU=1 -t irl-relay .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --device /dev/dri -v $HOME/irl-relay-data:Z:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

cd $HOME/irl-relay && docker build --build-arg WITH_OBS=1 -t irl-relay-obs .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -p 6080:6080 -v $HOME/irl-relay-data:Z:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay-obs

cd C:\irl-relay
docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -v irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

ipconfig

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

curl.exe -s http://localhost:8780/api/ping

ipconfig

docker inspect irl-relay | Select-String CONTROL

docker rm -f irl-relay

docker logs irl-relay | Select-String -Pattern password

docker exec -it irl-relay sh

docker stats irl-relay

mkdir C:\irl-relay-backup
docker run --rm -v irl-relay-data:/data -v C:\irl-relay-backup:/backup debian:bookworm-slim tar czf /backup/irl-relay-data.tgz -C /data .

-e LICENSE_KEY=IRL1.xxxxx.yyyyy

docker rm -f irl-relay
cd C:\irl-relay
docker build -t irl-relay .

New-NetFirewallRule -DisplayName "IRL Relay video in" -Direction Inbound -Protocol TCP -LocalPort 1935 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "IRL Relay SRT in" -Direction Inbound -Protocol UDP -LocalPort 8890 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "IRL Relay control page" -Direction Inbound -Protocol TCP -LocalPort 8780 -Action Allow -Profile Private

docker run --rm --gpus all debian:bookworm-slim nvidia-smi

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp --gpus all -v irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

cd C:\irl-relay ; docker build --build-arg WITH_OBS=1 -t irl-relay-obs .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -p 6080:6080 -v irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay-obs

cd ~/irl-relay && docker build -t irl-relay .

docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -v irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay

ipconfig getifaddr en0

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

curl -s http://localhost:8780/api/ping

ipconfig getifaddr en0

docker inspect irl-relay | grep CONTROL

docker rm -f irl-relay

docker logs irl-relay | grep -i password

docker exec -it irl-relay sh

docker stats irl-relay

mkdir -p "$HOME/irl-relay-backup"
docker run --rm -v irl-relay-data:/data -v "$HOME/irl-relay-backup:/backup" debian:bookworm-slim tar czf /backup/irl-relay-data.tgz -C /data .

-e LICENSE_KEY=IRL1.xxxxx.yyyyy

docker rm -f irl-relay
cd ~/irl-relay && docker build -t irl-relay .

cd ~/irl-relay && docker build --build-arg WITH_OBS=1 -t irl-relay-obs .

docker rm -f irl-relay; docker run -d --name irl-relay --restart unless-stopped -p 8780:8780 -p 1935:1935 -p 8890:8890/udp -p 8889:8889 -p 8189:8189/udp -p 6080:6080 -v irl-relay-data:/data -e CONTROL_PASSWORD=choose-a-password -e PUBLIC_HOST=yourname.duckdns.org irl-relay-obs

services:
  irl-relay:
    build: .
    image: irl-relay
    container_name: irl-relay
    restart: unless-stopped
    ports:
      - "8780:8780"
      - "1935:1935"
      - "8890:8890/udp"
      - "8889:8889"
      - "8189:8189/udp"
    volumes:
      - /volume1/docker/irl-relay-data:/data
    environment:
      - CONTROL_PASSWORD=choose-a-password
      - PUBLIC_HOST=yourname.duckdns.org

cd /volume1/docker/irl-relay && sudo docker compose up -d --build

docker ps

docker logs --tail 100 irl-relay

docker restart irl-relay
docker stop irl-relay
docker start irl-relay

docker inspect irl-relay | grep CONTROL

docker logs irl-relay | grep -i password

docker stats irl-relay

cp -r /volume1/docker/irl-relay-data /volume1/docker/irl-relay-data-backup

cd /volume1/docker/irl-relay && sudo docker compose down && sudo docker compose up -d --build

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, video, compute, utility]

Quick start

1. Run the container (see Set up on your system) and open http://YOUR-SERVER-IP:8780. Log in with the password you chose.
2. Inputs: use the phone input that is already there, or add more. Each input shows the address and key to type into your phone app or OBS.
3. Destinations: press Add destination, pick the platform (Twitch, YouTube, Kick, TikTok…) and paste the stream key from that platform. The server address is filled in for you where it never changes; Kick, TikTok and a few others also need the server address from the platform.
4. Switch the destination on, then press Start program. It checks that it can reach every destination that is switched on, and refuses to start if there are none or one can't be reached.
5. Start streaming from your phone. When its picture appears under Inputs, press Switch to this (or click the input).
6. Test with a private or unlisted stream before going public.

Ports and your router

These are the ports the container uses. You only need to open the ones for the way you send video to the server from outside your home.

Everything else (the internal receiver on 8554 and 9997) stays inside the container and must never be opened.

Setting up the router

1. Give the server a fixed address on your home network. In your router, reserve a DHCP address for it (for example 192.168.1.131) so it never changes. Find the current one with hostname -I on the server.
2. Forward the ports. In the router's Port forwarding (sometimes Virtual servers or NAT) page, add: external 1935 TCP → the server's address, port 1935; and external 8890 UDP → the same address, port 8890. Make sure UDP is really selected for SRT.
3. Find your public address. Search "what is my IP" from a computer on your home network. That is what your phone uses when you are out. Home IPs change now and then, so a free dynamic-DNS name (DuckDNS, No-IP…) is better: you use yourname.duckdns.org and it always points home.
4. Tell IRL Relay that address so the control page shows the right URL: start the container with -e PUBLIC_HOST=yourname.duckdns.org (see Set up on your system). Without it the page shows whatever address you opened it from, which is usually the home one.
5. Test it: on the control page use Check my ports. It asks cwtch.es to try to connect to your home connection from the internet and tells you which ports answer (RTMP 1935, SRT 8890, and the preview port). It only ever tests the connection it is asked from, and your address is not kept (only a rate-limit counter that disappears after an hour). You can also turn off wifi on your phone and try a real stream.

If your internet provider uses CG-NAT

Some providers share one public address between many customers. This is called CG-NAT (carrier-grade NAT). It is common on mobile and 5G home internet, and on some cable and fibre plans. You can't forward ports on an address you share, so a phone away from home can't reach your relay directly. A home-address name can't fix that either: it would only point at the provider's shared address.

How to tell:

• Your router's status page shows a "WAN IP" that starts with 100.64 to 100.127, or one that differs from what a "what is my IP" website shows from a computer at home.
• You've forwarded the ports correctly and Check my ports still says nothing is reachable.

What you can do:

• A VPN (Tailscale or WireGuard). The phone and the relay talk through the VPN, which works through CG-NAT with no router changes. This is the most reliable fix. Use the relay's VPN address as the server address in the phone app.
• Ask your provider for a public address. Many will take you off CG-NAT for free or a small fee. Ask for a "public IPv4" or a "static IP".
• Run the relay on a cheap VPS (a small rented server with its own public address) instead of at home.
• IPv6. Some CG-NAT connections still have working IPv6. If your relay reaches the internet over IPv6, a home-address name gets an IPv6 (AAAA) record. You'd also need to allow inbound IPv6 for the relay's ports in your router's firewall, and your phone network must support IPv6. Worth a try, but less predictable.

What still works behind CG-NAT: everything that only needs the relay to reach out: sending to Twitch and other destinations, the cwtch.es remote, helpers, chat commands, Discord alerts, licence checks and updates. Streaming from inside your own home network works too. It's only video coming in from outside your home that needs an inbound connection.

Tailscale: the easy way round CG-NAT

Tailscale makes a private network between your devices. Your phone and your relay get private addresses (starting 100.) and can reach each other from anywhere, with no router changes and no port forwarding. It's free for personal use. Only your own devices, signed in to your Tailscale account, can use it.

Or install Tailscale on the server itself (the long way, outside IRL Relay):

1. Make a free account at tailscale.com (you sign in with Google, Microsoft, GitHub or Apple).
2. Install Tailscale on the computer that runs the relay. The steps for your system (Unraid, Linux, Windows, Mac, NAS) are under Private network in Set up on your system. On Linux it is the command below.

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

3. Install the Tailscale app on your phone (App Store or Google Play) and sign in with the same account. Leave it switched on while you stream.
4. Find the relay's Tailscale address. On the server run the command below. It prints something like 100.101.102.103. (The Tailscale admin page at login.tailscale.com/admin/machines shows it too.)

tailscale ip -4

5. Use that address in your phone's streaming app instead of your home address:
   • RTMP: rtmp://100.101.102.103:1935/live with your stream key
   • SRT: srt://100.101.102.103:8890?streamid=publish:live/YOURKEY
6. Optional: start the relay with -e PUBLIC_HOST=100.101.102.103 (see Set up on your system) so the control page shows these addresses ready to copy. Leave the home-address name off, it isn't needed.

If the video is choppy: Tailscale prefers a direct connection between the two devices, and falls back to a slower relayed one if it can't make one. Check which you have with the commands below. If it says relay, give it a few seconds, then try again. A direct connection (direct) is what you want.

tailscale status
tailscale ping YOUR-PHONE-NAME

If it won't connect: check the phone shows the Tailscale key icon (connected), that both devices appear as Connected on login.tailscale.com/admin/machines, and that you used the 100. address, not your home one. If the relay runs in Docker, the ports are already published on the server, so they're reachable on its Tailscale address too.

WireGuard: your own private network

WireGuard does the same job as Tailscale, but you run it yourself. It's worth it if you'd rather not use an account with a third party, or you already use it. There are two cases.

1. You have a public address (no CG-NAT). Your router or server is the WireGuard server and your phone connects to your home.

• Unraid: open Settings → VPN Manager, set it to Remote access to server, and press Add peer for your phone. Scan its QR code with the WireGuard app on the phone. Forward the UDP port it shows (by default 51820) to the server in your router.
• A router with WireGuard (OpenWrt, Fritz!Box, UniFi, Mikrotik, Asus and others): turn on its WireGuard server, add a peer for your phone, and scan the QR code or import the file in the phone app. Router menus differ, so look for "WireGuard" in its settings or manual.
• Once connected, use the server's home network address (like 192.168.1.50) as the server address in the streaming app, with the same ports.

2. You are behind CG-NAT. Nothing can connect in to your home, so both your relay and your phone connect out to a small always-on server on the internet (a cheap VPS with a public address). That server just passes traffic between them, so use one you trust. It doesn't need to be fast. If this sounds like a lot, Tailscale above does all of it for you.

Steps below use 10.8.0.1 for the VPS, 10.8.0.2 for the relay and 10.8.0.3 for the phone. Do the first two on the VPS (Debian or Ubuntu).

sudo apt install wireguard qrencode
umask 077
for n in hub relay phone; do wg genkey | tee $n.key | wg pubkey > $n.pub; done
cat *.key *.pub

That prints six lines. Keep them handy: you'll paste each key into the right place below. A .key file is a private key. Never share those, and only put each one on its own device.

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = HUB.KEY-VALUE
PostUp = sysctl -w net.ipv4.ip_forward=1
PostUp = iptables -A FORWARD -i wg0 -o wg0 -j ACCEPT
PostDown = iptables -D FORWARD -i wg0 -o wg0 -j ACCEPT

[Peer]
# the relay
PublicKey = RELAY.PUB-VALUE
AllowedIPs = 10.8.0.2/32

[Peer]
# the phone
PublicKey = PHONE.PUB-VALUE
AllowedIPs = 10.8.0.3/32

sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0
sudo ufw allow 51820/udp

[Interface]
Address = 10.8.0.2/24
PrivateKey = RELAY.KEY-VALUE

[Peer]
PublicKey = HUB.PUB-VALUE
Endpoint = YOUR-VPS-ADDRESS:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25

sudo apt install wireguard
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

[Interface]
Address = 10.8.0.3/24
PrivateKey = PHONE.KEY-VALUE

[Peer]
PublicKey = HUB.PUB-VALUE
Endpoint = YOUR-VPS-ADDRESS:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25

qrencode -t ansiutf8 < phone.conf

• Check it: on the VPS run sudo wg show. Both peers should show a recent latest handshake. From the relay's server, ping 10.8.0.1 should answer.
• Stream: with the tunnel switched on in the phone, use rtmp://10.8.0.2:1935/live (or srt://10.8.0.2:8890?streamid=publish:live/YOURKEY) and your stream key. Optionally start the relay with -e PUBLIC_HOST=10.8.0.2.
• Tidy up: once every key is in its place, delete the key files and phone.conf from the VPS with shred -u phone.conf *.key. The hub's key stays safe inside wg0.conf.
• Note: your phone's video goes to the VPS and back to your home, so it uses the VPS's traffic allowance twice. A plan with a few hundred GB a month is plenty for one stream.

Sending video in

Each input on the control page shows its own address. Use one input per camera (or phone), and never share a key between two devices.

Phone tips: use the public address (not the 192.168… one) when you're out; 720p at 2.5 to 4 Mbps is a sensible mobile start; keep the phone's own bitrate at or below what your connection can really do. Bonded or multi-SIM apps help a lot on the move.

Inputs are always ready. The server decodes the latest picture of every input all the time, so switching is instant. Inputs that aren't on air still use a little CPU.

Destinations (Twitch, YouTube, Kick…)

• Pick the platform and paste only the stream key. For Twitch, YouTube, Facebook, Trovo and Restream the server address is built in. Kick, TikTok, Instagram, X and "Other" give you a server address and key, so you enter both (for Kick, copy the Stream URL and the Stream key from your Kick dashboard; the trailing /app is added if it's missing).
• Keys are secrets. Anyone with a stream key can stream to that channel. The control page only ever shows the start of the address.
• Facebook, TikTok, Instagram and X usually give a new address and key for each broadcast, so you update them before going live.
• Start program checks them first. It needs at least one destination switched on and must be able to reach every switched-on one. It can confirm that the server exists and answers; it can't tell if the key is right, so check the destination's state after starting (“live” means the platform accepted it).
• A destination that shows waiting keeps retrying by itself every few seconds, which is normal while the program starts or after a short drop.

Bandwidth: what your home connection needs

Vertical (portrait) streaming: in Picture quality choose one of the Vertical sizes (720×1280 or 1080×1920, Pro for 1080) if you mainly stream to vertical platforms such as TikTok or Instagram. The whole program, and so every destination, then goes out in portrait. A portrait phone fills the frame; a landscape input is shrunk to fit with black bars above and below. A destination never sees your input, only the program, so the size is always the one you picked here.

If your upload is limited, send to fewer destinations, or lower the quality under Picture quality. Many platforms also offer their own multi-streaming, which is lighter on your connection.

Free and Pro

• Get a key: a paid key, or if you are subscribed to the channel on Twitch, open Plan and licence → Subscribed on Twitch? Get your free Pro key. Log in with Twitch, copy the key, paste it on the Licence panel.
• Subscriber keys last about a month. Come back to the same link for a fresh one while you are still subscribed. The panel warns you a few days before it ends.
• The app checks in with cwtch.es when you paste a key and about every 6 hours. If the site can't be reached, Pro carries on for up to 7 days (3 days on a first-ever activation) and comes back by itself as soon as it can connect. So the server needs normal internet access.
• One key works on up to 3 installs. A key that is shared around further, or switched off, drops to Free at the next check.
• Going back to Free never deletes anything. Extra inputs and destinations are kept and just locked until you have Pro again.

What else it does

Use OBS inside the relay (advanced)

The normal image runs on almost anything. If your server is a stronger computer, you can build a second image that has OBS Studio inside. OBS takes your phone's picture, adds your scenes, then sends its result back into the relay as an input called OBS. The relay is still in front of Twitch and Kick, so the Be-right-back protection, destinations and recording work as usual, even if OBS stops.

To install it: the exact commands for your system are under OBS inside the relay in Set up on your system. In short, you build a second image with --build-arg WITH_OBS=1 and start it with the extra -p 6080:6080 for the remote desktop.

Then:

1. Open Settings → OBS (advanced), choose which input OBS should capture (your phone or PC) and press Turn on OBS. It starts in about a minute. It adds an input called OBS (this counts towards your plan's input limit) and two scenes: Live (your phone's picture) and BRB.
2. On the Live tab you get buttons for OBS's scenes. To send OBS to your viewers, press Switch to this on the OBS input, like any other input.
3. If the phone stops, OBS shows its BRB scene by itself (switch this off in the OBS settings if you'd rather it didn't). It only moves between the scenes named Live and BRB.

Editing scenes. Switch on Remote desktop in Settings → OBS and press Open OBS desktop. You see the full OBS window in your browser and can add images, videos, text, filters, more scenes and so on, like normal OBS. The page asks for the password shown in the same panel. Use it at home or over your private network (Tailscale), don't forward port 6080 on your router, and switch it off when you're done. Your scenes are kept in the data folder, so they survive updates.

Good to know. OBS sends to the relay by itself, so don't press Stop Streaming inside OBS (it will start again by itself after a few seconds). A video, audio or image file can't be added from your own computer: put the files in the data folder (obs/ inside it) and add them from there. Reset scenes puts the two starting scenes back. Turn off OBS removes the OBS input and stops it, and keeps your scenes for next time. If OBS won't start, the panel says why; the details are in obs/obs.log in the data folder.

Use a graphics card for the video (optional)

By default the relay does the video encoding on the computer's processor. That works everywhere and is the right choice for most people. If the server also has a graphics card, the card can do that work instead, which leaves the processor free for other things (or lets a small server cope with a higher quality). You choose it under Settings → Quality → Encoder.

Which kind do I have? An NVIDIA graphics card → NVIDIA. The graphics built into most Intel processors, or an AMD graphics card or processor → Intel or AMD. The container has to be given the card when it starts, and how depends on your system: the commands are under Graphics card in Set up on your system (Unraid, Ubuntu & Debian, Other Linux, Windows, NAS).

Good to know. A hardware encoder gives about the same picture as the processor at the same bitrate, sometimes a touch softer; if you notice, go up one quality step. Some NVIDIA GeForce cards only allow a few encodes at once, and each destination you send a different input to (Pro) uses one more, so if Test mentions the card being busy or at its limit, close other programs that use the card's video encoder (Plex, OBS, a second relay). This is a new feature: if it never works on your card, the relay keeps streaming on the processor and the message says what it found. Mac, and Intel or AMD graphics on Windows, can't pass a card through, so use the processor there.

Starting-soon screen

A second still screen for before you go live. Add the destinations, start the program, leave it on Starting soon while people arrive, then switch to your input when you're ready. Change its words under Starting-soon screen. Chat command: !soon (!switch soon works too).

A cwtch.es overlay on these screens PRO

Instead of plain words, the Starting-soon and Be-right-back screens can show a page from your cwtch.es dashboard, such as the Next Stream Countdown, Big Countdown Timer or Stream Overlay Text Cards. Copy that tool's OBS link from your dashboard, paste it under the screen's text box and press Save. A small web browser inside the app draws it, only while that screen is on air (it takes a couple of seconds to appear; the plain screen shows meanwhile), and it fills the picture. Only cwtch.es links are accepted, and sound from the page isn't included. If a page is set, it is used instead of your clips on the Be-right-back screen. This needs the latest Dockerfile (it adds the browser), so rebuild the image after updating. It makes the image a few hundred MB bigger.

Be-right-back screen

If the input on air loses signal, viewers see the Be-right-back screen instead of a frozen picture or a dead stream. Change the words under Be-right-back screen. PRO Turn on Clips on the Be-right-back screen to play your newest Twitch clips, with sound, instead of the still picture: press Connect Twitch to get a token, approve the single permission (Twitch requires "manage clips" before it shares clip downloads; nothing is ever created or deleted), paste the token and switch it on. Clips are saved on the server and refreshed every half hour.

Automatic backup switching PRO

Choose a main input and a backup. If the main one drops (or falls under the minimum bitrate you set) for a few seconds it switches to the backup, and switches back once the main has been good for a while. Turn on Be-right-back as the backup if you don't have a second camera. Two shortcuts: for Main input choose Whichever input I'm on air with and it protects whatever you last switched to by hand; for Backup choose Any other live input, then Be-right-back and it uses the first of your other inputs that has a signal (and moves on if that one drops too), falling back to the Be-right-back screen.

cwtch.es remote PRO

Control the relay from a page on cwtch.es without opening any port. In the cwtch.es remote panel press Link this relay: it shows a one-time code. Open cwtch.es/irl-remote.html on your phone or any computer and type the code. You then get the same big buttons as the phone remote (switch input, Be-right-back, Starting-soon, Go live/Stop, destinations on/off). Your relay checks in with cwtch.es by itself, every 15 seconds, or every 2 seconds while a page is open; nothing ever connects in to your home network. Only those few actions can be done this way: no settings, stream keys or files are reachable, and cwtch.es only holds your input and destination names and on/off state. A button can take a few seconds to take effect. Each paired phone or browser is listed by name in the same panel with a Remove button, and Unlink removes every paired device at once. A code works once and runs out after 15 minutes. Paired devices stay paired until you remove them; if you prefer, tick Let each pairing run out after 30 days and they have to pair again after that. It needs a Pro licence that has been activated.

Home-address name PRO

In Settings, Home-address name gives this relay a name like k7p4q-9xmh3t-2wb6nd.cwtch.live that always points at your home connection, even when your internet provider changes your address. This relay tells cwtch.es now and then (cwtch.es sees the address from the request itself) and cwtch.es keeps the name up to date, so the server address in your phone app or OBS never needs changing. You still need the router forwards from Ports and your router; the name only replaces the number. It is off by default, because it puts your home address in public DNS under that long random name; turning it off removes the name. A name that hasn't been seen for 30 days is removed. It doesn't help behind carrier-grade NAT, where the provider shares one address between many customers (see CG-NAT).

Helpers: let your mods log in with Twitch PRO

Once the relay is linked, the Helpers list in the same panel lets chosen people (your moderators, say) open cwtch.es/irl-remote.html and press Log in with Twitch instead of using a code. Add their Twitch names and choose what each may do: Switch scenes only (they see the input buttons, nothing else) or Full control (they can also start and stop the stream and switch destinations). Only names on your list get in. Twitch tells cwtch.es just the person's name; no stream keys, settings or files are ever reachable. Add the names from my chat commands copies your chat-command list in as scenes-only helpers. To cut someone off, remove their name: it takes up to 15 seconds. (Remove on a paired device only logs that device out, so a helper could log in again until their name is gone.) Your own phones keep using pairing codes.

Overlay on the video PRO

Draws a cwtch.es widget (a countdown, goal bar, alert box and so on) over whatever is on air, for every destination and for recordings. In your cwtch.es dashboard copy the widget's OBS link, paste it in the Overlay on the video panel, pick a position and size, and switch it on. Use a widget with a see-through background (they are by default) so the picture shows around it. Showing and hiding it is instant. The first time you set it, and whenever you change the page, the size or the position, the stream restarts for a moment (your destinations reconnect) because the video encoder has to be rebuilt to make room for it. It's drawn by the small web browser inside the app, only while the stream is running, and needs the latest Dockerfile (it adds Chromium). Destinations set to a single input don't get the overlay.

Picture-in-picture PRO

Show a second input as a small picture (a quarter of the width, with a thin white border) in a corner of whatever is on air. Pick the input and the corner in the Picture-in-picture panel and switch it on. It shows while the small input has a signal and isn't the one on air, disappears by itself if that input drops, and never appears over the Be-right-back or Starting-soon screens. Only its picture is used; its sound isn't mixed in. It's drawn on the main program, so destinations set to one input don't get it.

Different input to one destination PRO

Normally every destination gets the same picture (the program). With two or more inputs, each destination has a menu next to Edit: Main program (the default) or Only <input>. For example, send your camera to YouTube while Twitch follows whatever you switch to. A destination set to one input always shows that input, and shows the Be-right-back card if that input has no signal, and it isn't affected by switching or by automatic backup switching. Each different input you route to adds one extra encoder, which uses more processor and has the same picture quality settings as the main one. The extra encoders only run while the program is running. Removing an input puts its destinations back on the main program.

Volume and mute per input

Each input card has a Sound button (tap to mute) and a volume slider from 0 to 200%. 100% leaves the sound as it arrives. Use it to quieten a noisy camera mic or lift a quiet phone. It only changes the sound viewers hear; the input itself is untouched. Going above 100% can distort loud sound.

Auto-start and auto-stop PRO

Start when an input connects: while the program is stopped, the moment a phone or camera starts sending (and keeps sending for a few seconds) the stream starts by itself, showing the input that connected. If you stop it by hand while the phone is still sending, it stays stopped until something connects again. Stop when nothing has been connected for: ends the stream once no input has been sending for the number of minutes you choose, so you aren't left streaming a Be-right-back screen to nobody. A countdown shows on the panel. The Starting-soon screen never triggers an auto-stop.

Discord alerts PRO

Posts a message in a Discord channel of your own when you go live or stop, when the input you're on air with drops or comes back, when you switch input, and when a destination loses its connection. In Discord open the channel's settings → Integrations → Webhooks → New webhook → Copy Webhook URL, paste it into the Discord alerts panel and use Send a test message. Pick which kinds of message you want. Messages never ping anyone. The webhook address stays on this server (and in a settings backup); anyone who has it can post in that channel, so keep it private.

Phone remote

Open http://your-server:8780/remote on your phone (or tap Phone remote at the top of the control page) for a page made for thumbs: big buttons to switch input, Be-right-back and Starting-soon, a Go live button (stopping asks for a second tap so you can't do it by accident), and a switch for each destination. It uses the same password as the control page. Add it to your home screen for one-tap access.

Chat commands PRO

You and your mods steer the stream from Twitch chat: !brb (Be-right-back screen), !soon (Starting-soon screen), !back (main input), !switch 2 or !switch name, !inputs, !status. Everyone else is ignored. By default every moderator can use them, plus any Twitch names you add to the list. To let only certain moderators in, set Who can use commands to Only the names below and list their Twitch names; other moderators are then ignored (you, as the channel owner, always can). It listens without logging in; for it to reply in chat, add a bot account name and that account's chat token.

Live preview

The What viewers get box under the inputs is live video of the program (shown while the program is running). To watch one input before you switch to it, click its picture: a window opens with that input live, as it arrives from the device. The small pictures on the cards are only snapshots that refresh every couple of seconds. Live video uses ports 8889 (TCP) and 8189 (UDP). At home that just works; away from home they need forwarding too, and the page must be opened over plain http:// (a secure https:// page can't embed it).

Live stats

The Live stats section shows each input's bitrate for the last couple of minutes, how often it dropped and when, plus how long each destination has been live.

Recording PRO

Saves what viewers see to an MP4 on the server (about 1.5 GB per hour at 3000 kbps). Download or delete recordings from the panel. They live in the data folder under recordings.

Troubleshooting

Password, two-step login and settings

To see or change the password, use the commands under Everyday commands in your system's tab (Set up on your system): you remove the container and start it again with a new CONTROL_PASSWORD, and your settings are kept. The password you give at start always replaces the saved one.

Two-step login (2FA)

Turn it on in Settings → Two-step login: scan the picture with an authenticator app, type the 6-digit code once, and save the recovery codes it shows. After that, logging in (here and on the phone remote page) needs the password and a code.

• Scripts and tools that log in with only the password stop working while it's on. Turn it off if you rely on one.
• Five wrong codes in a row lock the code step for five minutes.

Other

New-version notice. About twice a day the control page asks one public file on cwtch.es which release is newest, and shows a banner if yours is older. It sends nothing about you (only the version number). To switch it off, add -e UPDATE_CHECK=0 to the docker run line.

You can also save your settings from the control page: Backup and restore → Download a backup. To put them back (on this computer or a new one), use Restore from a backup… and pick the file. It restores your inputs, destinations, picture settings, screens, automatic switching, chat and clips settings, and your licence. It does not include the control password or recordings. The file contains your stream keys, so keep it private.

Start with a Pro key. You can paste a key on the Licence panel, or add -e LICENSE_KEY=IRL1.xxxxx.yyyyy to the run line.

Staying safe

• Don't forward port 8780. The control page can switch your stream and holds your stream keys. If you need it away from home, use a VPN (Tailscale, WireGuard) rather than opening it to the internet.
• Choose a long password, and turn on two-step login (Settings) if the relay can be reached from outside your home. Anyone who gets in controls your stream.
• Treat input keys and destination keys like passwords; if one leaks, make a new one.
• Your licence key, clips token and chat token are stored on the server in the data folder. Keep backups private.
• Keep the program folder as it came. Editing the program files shows a warning on the control page and tells the licence server your copy was changed.

IRL Relay · help · control page