roku-remote — Build Recipe

Take a bare machine to a running web-based Roku remote: a phone-friendly single-card UI backed by an Express + tRPC server that discovers Roku devices, controls them over Roku's External Control Protocol (ECP), quick-launches 13 streaming channels, and tracks each device by serial number so control keeps working even after the TV's DHCP IP changes. Runs with no real hardware, no keys, and no SSDP multicast — a small bundled mock Roku plays the part of the TVs so the whole thing is demoable on any Docker host.

Status: ✅ Verified 2026-08-02 — built from this clone on a Linux Docker host (docker compose up -d --build). Both services came up healthy; the web app served on :8094 and its seeded fake devices (Living Room / Bedroom / Kitchen) populated the picker with no real hardware and no SSDP. A real-browser pass selected a device and pressed Home, and the mock Roku received the ECP keypress end-to-end (Living Room Roku <- keypress Home), with 0 console errors. All three tiers covered; the prebuilt tarball (docker save roku-remote-clone roku-remote-mock-clone) is ~430 MB.

Sensitive data: none. The four real household Rokus (names, LAN IPs, serials, MACs) were replaced with invented devices; the Manus OAuth/JWT scaffolding was stripped; the app runs key-free and device-free.

Sensitive data: none in this clone. The personal version stored four real household Rokus (names including a family surname, LAN IPs, serial numbers, MAC addresses) in a device file, carried a hardcoded JWT_SECRET, and pointed at the Manus OAuth platform. All of that is replaced with three invented demo devices served by the mock, and every Manus/auth/database scaffold was removed or neutralized. See What was stripped.

What it is

Two small services on one compose network:

Stack: TypeScript throughout, tRPC over HTTP (superjson), node-ssdp for discovery, axios for ECP, Tailwind 4 + shadcn/ui for the single remote card. No GPU, no database, no API keys.

Prerequisites

New machine? See ../SETUP.md for Docker. Then, per tier:

Configuration — nothing required

Runs key-free and device-free out of the box. The three demo Rokus are seeded into the device store on first boot, and their serial numbers match what the mock reports — so the app's serial-keyed fast path resolves them live with no real TV. Everything is env-overridable (clone/.env.example), but the defaults in docker-compose.yml need no editing.

Tier 1 — Run the prebuilt containers (recommended)

Availability: the prebuilt image bundle is available on request — it is not published or linked anywhere. Ask Kevin for it, or build from source via Tier 2 below.

docker load -i roku-remote-clone-image.tar   # loads both images
cd clone
docker compose up -d                         # → http://localhost:8094

Tier 2 — Build from source

cd clone
docker compose up -d --build                 # → http://localhost:8094
curl -s localhost:8094/health                # → {"status":"ok"}

Open http://localhost:8094. The device dropdown is already populated with the three demo Rokus. Pick one, then press buttons — the mock logs each keypress (docker compose logs -f mock-roku), and the UI toasts success/failure exactly as it would against a real TV.

Tier 3 — Bare-metal (two Node processes)

cd clone

# 1) the mock Roku (answers ECP on :8060)
cd mock-roku && npm install --omit=dev && node server.js &      # → :8060
#   The three demo devices are addressed by hostname; for a single-host bare-metal
#   run, point one seed device at localhost (see note below).

# 2) the controller
cd ..
npm install --legacy-peer-deps
npm run build                                                    # vite + esbuild
ROKU_SSDP_ENABLED=false \
ROKU_SEED_HOSTS=127.0.0.1 \
ROKU_STORAGE_PATH=./data/roku-devices.json \
PORT=8094 npm start                                              # → http://localhost:8094

On bare metal the compose network aliases (roku-bedroom, …) don't exist, so the mock's three devices all answer on 127.0.0.1:8060 and the app resolves whichever one the Host header selects (it defaults to the living-room device). The Docker path is the honest multi-device demo; bare-metal is the "it's just two Node processes" proof. On Windows, set the env vars with $env: first.

Optional: point it at your real Rokus

This is the whole reason the project exists. To drive actual TVs instead of the mock:

1. Run the controller with host networking (so it can send SSDP multicast on UDP 1900) and enable discovery: yaml # docker-compose.override.yml services: roku-controller: network_mode: host environment: - ROKU_SSDP_ENABLED=true (Drop the mock-roku service and the ports: mapping when using host networking.)
2. Or skip SSDP entirely and list your TVs' LAN IPs: ROKU_SEED_HOSTS=192.168.1.50,192.168.1.51, or add them one at a time with the + button in the UI (enter the IP; it connects, reads the serial, and saves it).

Either way ROKU_ECP_PORT stays at the Roku default of 8060. Once a device is stored by serial, its IP can change freely and control still works.

Provenance — data & devices

No datasets, no models, no keys. mock-roku/server.js and seed/roku-devices.json contain three invented devices with fake, self-consistent names, models, serial numbers, and MAC addresses (DEMOROKU0001…3, aa:bb:cc:00:00:0x). The channel IDs in shared/rokuChannels.ts are Roku's public, well-known app IDs (Netflix 12, YouTube 837, Jellyfin 592369, …) — not personal data.

What was stripped from the personal version (de-identification)

• The real household Rokus — the live device file held real device names (one revealing a family surname), LAN IPs, serial numbers, and MAC addresses, and the discover/addDevice API returned them to any LAN client with no auth. Replaced entirely with the three invented mock devices.
• The hardcoded seed IP baked into the discovery fallback (a fixed real home-LAN address) → replaced with an env-driven ROKU_SEED_HOSTS list (empty by default, pointed at the mock in compose).
• A hardcoded JWT_SECRET and the Manus OAuth platform dependency → removed; the clone has no auth layer and makes no external calls. (The app is LAN-only by design; see limitations.)
• The dead database layer — a drizzle-orm/mysql2 schema plus a bogus DATABASE_URL=file:/app/data/roku.db (a SQLite URL pointed at a MySQL driver that never connected). Persistence was always the JSON file; the DB code and env var are gone.
• The Manus template scaffolding the app was generated inside — the unused _core LLM / voice / map / image-generation modules, the OAuth/JWT session plumbing, the vite Manus-runtime plugin and 800-line browser debug collector, and ~45 unused shadcn components / ComponentShowcase / demo pages. Kept only the shadcn primitives the remote actually uses (button, card, dialog, input, label, select, sonner, tooltip).
• The hardcoded ECP port (:8060 in three places) → parameterized via ROKU_ECP_PORT so the app can be aimed at the mock, and SSDP was made opt-in (ROKU_SSDP_ENABLED, default off) so the clone runs on a plain bridge network instead of requiring host networking.
• Added a plain GET /health route (the original's healthcheck curled one that only existed as a tRPC procedure).

Known limitations (stated honestly)

• No authentication — like the original, every procedure is public. This is a trusted-LAN tool; don't expose it to the internet as-is (anyone who reaches it could control the TVs and read device serials/MACs).
• The mock is a stand-in, not a Roku. It returns valid ECP device-info and 200s every keypress/launch, but there's no on-screen effect to see — the demo proves the control path (discovery → serial resolution → ECP call), not a picture on a TV. The real payoff is pointing it at hardware.
• Bare-metal collapses the three devices onto one host (127.0.0.1:8060), since the multi-device illusion relies on docker-compose network aliases. Use the Docker path for the full three-device dropdown.
• Search is wired but has no button, and removeRokuDevice exists with no UI — both carried over faithfully from the original as-is.

The engineering story (why this is worth showing)

The signature lesson came from a real failure: button presses silently stopped working because the Rokus picked up new DHCP leases, and the app had been keyed on IP address. The fix — carried into this clone verbatim — is to make the serial number the stable identity end to end:

• The UI addresses commands by serialNumber, never IP (the dropdown doesn't even show IPs).
• resolveDeviceIP(serial) runs a fast path / slow path: try the stored IP and verify it still reports the expected serial via device-info; if it's stale, run full re-discovery, match by serial, update the stored IP, then send the command. So a TV that moved to a new IP is silently re-found on the next press.
• Discovery itself is a fallback chain: SSDP M-SEARCH roku:ecp (filtered by the Roku SERVER header) when enabled, degrading to a known-host scan and a seed list. ECP XML is parsed by a handful of regexes — no XML library — because only four fields matter.

The mock exists to make all of that observable without a TV: three fake devices behind docker-compose network aliases let the controller resolve each one by host exactly as it would by IP on a real LAN, so the serial-keyed fast path, the stale-IP re-resolution, and the ECP request/response are all exercised end to end, key-free and hardware-free.

The original was generated with the Manus AI agent (not Claude); this clone keeps the first-party Roku logic and rebuilds everything around it as a clean, self-contained, key-free project.