Getting Started

RelayTV turns a Linux box connected to your TV into a local playback target. This guide covers installing the server, then adding the Android companion app and the Home Assistant integration.

Requirements

A 64-bit (amd64 or arm64) Linux host connected directly to a television — Raspberry Pi-class devices, Intel mini PCs, NUCs, and HTPCs all work
A graphical desktop session on that host — a Wayland or X11 desktop that auto-logs in on the connected display (RelayTV renders playback through it)
Docker (the installer can set it up with your approval when needed)
A trusted LAN — use a VPN or authenticated reverse proxy rather than exposing the API to the public internet

Install

One command on the box connected to your TV:

mkdir -p ~/relaytv
cd ~/relaytv
curl -fsSL https://relaytv.app/install.sh | bash

relaytv.app/install.sh serves the current bootstrap installer from the main repository. It downloads the release compose files and pulls the published container image (ghcr.io/mcgeezy/relaytv:latest). Run install.sh --help for options like --dir, --branch, and --image.

Need runtime choices, hardware notes, or an existing source checkout? See the complete installation guide. Release notes for each version live on the releases page.

First run

Open the Web UI from any phone or desktop browser on your network:

http://YOUR_RELAYTV_HOST:8787/ui

From there you can paste a media URL to play or queue it, connect a Jellyfin or Emby server to browse your library, and optionally enable IPTV playlists (M3U URLs, pasted lists, or the built-in free-provider directory — disabled by default).

Updating

cd ~/relaytv
docker compose pull
docker compose up -d

Android companion app

RelayTV for Android (Android 8.0+) gives you a fast mobile remote and share targets for your TV:

Share to TV — share a link from YouTube or any app and pick RelayTV Queue (adds to the queue) or RelayTV Play (plays immediately)
LAN auto-discovery — finds _relaytv._tcp servers on your network via mDNS
System media controls — lock-screen and quick-settings controls mirror what's playing on the TV
Multi-server — manage more than one RelayTV box from one app, over HTTP or HTTPS

Grab the latest APK from GitHub Releases, or build from source — instructions are in the repository README.

Home Assistant integration

RelayTV for Home Assistant (2026.7+) makes every RelayTV screen a real media_player device — playback controls, live artwork, and progress on dashboards, mobile, and voice.

Install via HACS:

Open HACS, add mcgeezy/relaytv-ha as a custom repository (category Integration)
Install RelayTV and restart Home Assistant
Add it from Settings → Devices & Services → Add Integration, then enter your RelayTV base URL (e.g. http://relaytv-host:8787)

Beyond the media player you get RelayTV-specific actions — smart play, interrupt-and-resume, overlays, snapshots, synchronized multi-screen start — plus an optional sidebar panel embedding the full Web UI, and a share automation that relays links from the Home Assistant mobile app straight to the TV.

HTTP API

Everything the apps do goes through the same local HTTP endpoint, so scripts and dashboards can too:

# Play a URL right now
curl -X POST http://YOUR_RELAYTV_HOST:8787/play_now \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video"}'

# Smart play: queues if something is already playing, otherwise plays
curl -X POST http://YOUR_RELAYTV_HOST:8787/smart \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video"}'

See the full API reference for status, queue management, overlays, and authentication with RELAYTV_API_TOKEN.

Full reference

Installation guide — runtimes, hardware notes, source checkouts
HTTP API
Jellyfin/Emby operations
IPTV operations
Architecture
Documentation map — all runbooks and inventories

Troubleshooting

Web UI not loading — confirm the container is running (docker ps, docker logs relaytv) and that you're using port 8787 with the /ui path.
No video on the TV — verify the display is attached and check the native runtime operations guide.
Android app can't find the server — auto-discovery needs mDNS on the same LAN; you can always add the server manually by URL.
Something else — open an issue on GitHub.