Couchside
Your phone is the dashboard, remote console, and game controller for your living-room Linux box.
Couchside pairs a native iOS & Android app with a tiny, dependency-free Python service that runs on a SteamOS / Bazzite HTPC, a Steam Deck, or any systemd Linux machine. When gamescope wedges into a black screen and the TV shows nothing, Couchside is the screen: see live vitals, read the logs, restart the display session, or become an Xbox 360 controller, all from the couch and entirely on your own LAN. No cloud, no accounts, no analytics.
Release versions
The phone app and the service on your gaming box have separate version numbers. Build numbers identify a specific app package and are counted separately for each distribution.
Store availability depends on review and rollout. See release notes for details. The latest signed service release is tagged v2.9.78; its title and agent-version.txt identify service version 2.9.134. The installers and updater use the stable latest-release URL. Historical releases remain available, and Direct downloads retain their stable couchside-direct tag.
See it in action
Real footage — a phone driving Steam Big Picture on the TV over the LAN, nothing staged.
| Navigate & switch input modes | Browse and launch the library |
|---|
| |
| Type from the phone | Big Picture & Quick Access Menu |
|---|
| |
The full install — one command, scan the QR, drive the box — is on the site: couchside.tv (terminal sped up, nothing else). Every release since launch is written up at couchside.tv/updates.
The gamepad UI on the phone and the Steam sidebar responding on the TV, at the same time:
Utilities: flash an OpenPuck receiver from the couch
Plug a cheap nRF52840 board into the box, open Setup → Utilities, and tap
Flash receiver — Couchside writes the OpenPuck
firmware and the board reboots as a Steam Controller 2 wireless receiver. No cable
juggling, no cp to a mystery mount, no terminal. Below is real footage, end to end:
a bare nRF52840 hanging off a USB cable, the flash driven from the phone, and then
Steam's own controller list showing a Steam Controller Puck attached — the same
board, one tap later (the wait during flashing is sped up slightly).
OpenPuck is a separate AGPL-3.0 project by safijari,
flashed here from the EmeryTech fork. Couchside
does not embed or compile it: the box downloads the released firmware binary from the
fork at flash time and writes it to the board you plugged in. Because Couchside distributes
that binary, the corresponding source is offered at the exact shipped tag
(0.9.40) — see the app's
Setup → Open source licenses screen and agent/openpuck/OPENPUCK-NOTICE.txt.
Features
- SteamOS Themes (Beta, optional): choose seven home layouts or make a draft in Theme Studio from Settings → Boxes → Steam appearance. Requires Decky Loader and an updated Couchside companion. Themes start off until you apply one; restore Steam default from the app or Decky panel at any time. Custom themes use a bounded settings format, not executable theme code.
- Live console: hostname, uptime, CPU temperature, load averages, memory and per-disk usage with color-coded bars, refreshed every few seconds. A big red BOX UNREACHABLE banner (with last-seen time) when the box drops off the network, which is exactly when you need it.
- systemd unit health: a watchlist of system and user units (display manager, the Couchside service itself, your own services) with active/failed state at a glance.
- One-tap runbook actions: grouped by what they interrupt, every action confirmed before it runs and double-confirmed when it ends your session:
- Restart display session fixes the classic wedged-gamescope black screen without touching anything else.
- Reboot / Power off are clean and fire-and-forget.
- Journal viewer: the last journald lines for any watchlist unit, newest first, straight from the phone.
- Virtual game controller: the service creates a real virtual Xbox 360 pad via
/dev/uinput; games and Steam Big Picture see genuine wired-360 input. Four input modes, switchable with one tap:
- Gamepad: full layout with dual analog sticks, D-pad, ABXY, bumpers, analog triggers, Start/Select/Guide, and haptic feedback.
- Swipe: an Apple-TV-remote-style surface. Swipe to move through menus, tap to select, plus Back / Guide / Menu buttons. Perfect for Kodi and Big Picture navigation.
- Trackpad: a relative-mouse trackpad with tap-to-click, two-finger right-click and scroll, for desktop sessions.
- Remote: a classic TV-remote layout — a big circular D-pad with OK, Back/Menu/Home/Settings keys, volume and brightness rockers, and Steam/QAM shortcuts. On an RS-232 panel it adds input-source buttons and a BOX/TV toggle that drives either the box (as the virtual gamepad) or the TV's own factory remote over serial.
- Pairing without typing: tap Scan for boxes and Couchside finds them on your network; the one you pick shows a PIN on its own screen and you type that in. The installer's QR code still works, and host/port/token lives behind for anyone who wants it.
Control your TV
Couchside can also drive a networked smart TV directly — no HDMI-CEC and no serial cable. Add one under Setup → Boxes → Smart TV remote: tap Scan for TVs and Couchside finds the sets on your network, so you don't have to hunt for an IP (you can still type one). Couchside identifies what is actually at an address before you try to pair with it, so aiming at the wrong device explains itself instead of just failing — and with more than one set on the network you choose which one the Pad drives, rather than getting whichever brand happens to rank highest. Once it's connected the Pad tab lights up with the D-pad, power, volume, the input/SOURCE key, and an on-screen keyboard — and your phone's own volume buttons drive the TV too.
- LG webOS — enter the TV's IP, then accept the pairing prompt that appears on the TV (once). An optional MAC address enables Wake-on-LAN power-on.
- Samsung (Tizen) (beta — not yet validated on real hardware) — enter the IP, then approve the "Allow" prompt on the TV. Optional MAC for Wake-on-LAN.
- Roku — enter the IP; no pairing. If the D-pad doesn't respond after adding, the Roku is blocking app control: on the Roku, set Settings → System → Advanced system settings → Control by mobile apps → Network access to Permissive.
- Android / Google TV — enter the IP, then type the 6-digit code the TV shows. Optional MAC for Wake-on-LAN.
- Hisense (VIDAA) — enter the IP, then approve the pairing code the TV displays. Note that Hisense sets running Google TV pair as Android / Google TV above, not as VIDAA.
- LG commercial / signage panels — the boardroom-and-hotel LG sets speak their own control protocol on a different port from consumer webOS, and are supported separately. No pairing prompt.
These network backends run on the Linux service. The Windows service supports Roku (from 0.3.6-win); LG / Samsung / Google TV / Hisense are Linux-only for now. TV control also works through the box when it has an HDMI-CEC link or an RS-232 serial panel (power, volume, input source, on-screen remote) — see the volume/power control above.
Requirements
- A SteamOS, Bazzite, or other systemd-based Linux machine on your home network (HTPC, Steam Deck in desktop/docked use, mini PC…). The service is pure Python 3 stdlib: no pip, and it works on immutable/ostree systems.
- Windows HTPC? There's a Windows service with the same API (
agent/win/) — services, Event Log, Steam launching + Big Picture, volume, and a ViGEm virtual gamepad. Install it in one line from PowerShell: irm https://couchside.tv/install.ps1 | iex.
- An iPhone or Android phone on the same LAN.
Install the service
On the box (or over SSH):
curl -fsSL https://couchside.tv/install.sh | bash
The installer copies the service to ~/.local/opt/couchside/, generates a token at /etc/couchside/token, installs a scoped sudoers rule, enables couchside.service, opens 8787/tcp in the local firewall, and finishes by printing a pairing QR code.
Steam Deck / SteamOS: a SteamOS update throws away every change in /etc that is not on its keep-list, so on SteamOS the installer also writes /etc/atomic-update.conf.d/couchside.conf, which lists only Couchside's own files there. If a box was installed before that and an update already took them, the app shows "Box installation is damaged". Re-running the installer command above in a terminal on the box (Desktop Mode on a Deck) puts them back. It keeps your existing pairing when the box still has its backup copy of the token, which Couchside 2.9.114 and later keep. An update started from the phone can't do this, because it has no password to write system files.
Decky Loader box? The installer also adds the Couchside Game Mode panel to Decky and lets it run the service. Don't want the panel? Remove Couchside in Decky's Settings → Plugins. The service keeps running, and the next update notices the panel is gone, remembers that (/var/lib/couchside/no-decky-panel) and runs couchside.service on its own from then on instead of putting the panel back. curl -fsSL https://couchside.tv/install.sh | bash -s -- --no-decky does the same up front; ... | bash -s -- --decky brings the panel back.
Running Bazzite? The same steps are in the official Bazzite documentation. On Windows, download CouchsideSetup.exe instead and double-click it.
Get the app
Free 7-day trial with every feature unlocked, then a one-time unlock ($4.99 summer launch price). Prefer to build it yourself? The app's full source is right here: clone this repo and run it on your own device for personal use (see app/LICENSE).
Pairing
Scan + PIN (recommended): on the Setup tab tap Scan for boxes. Couchside finds the boxes on your network, and the one you pick shows a PIN on its own screen — type that PIN into the app and it pairs itself. No IP, no port, no token to copy. The PIN appearing on the box's own display is the proof that you're the person sitting in front of it.
QR: point the phone camera at the QR code the installer prints. It's a couchside://setup?host=…&port=…&token=… deep link, so the app opens on the Setup tab with everything prefilled and runs a connection test automatically. Nothing is saved until you tap SAVE.
Manual (advanced): under Add by IP (advanced) enter the host (e.g. mybox.local), port (8787), and the contents of /etc/couchside/token, tap TEST, then SAVE.
Security model
Couchside separates local control, pairing and optional privileged operations:
-
Bearer token auth. Control APIs require Authorization: Bearer <token>; discovery and PIN pairing have separate gates. Native image reads and file uploads can instead use short-lived, scoped tickets. The gamepad WebSocket authenticates before the handshake completes. Comparisons are constant-time (hmac.compare_digest). The token file is chmod 600; on the phone it lives in the iOS Keychain / Android Keystore.
-
Scoped sudo, nothing more. The installer writes a visudo-validated sudoers file granting the service user passwordless sudo for a fixed set of exactly-argument commands — no wildcards, no globs, no directories. Six are always granted:
| grant | why |
|---|
systemctl reboot | |
systemctl poweroff | |
systemctl suspend | |
systemctl restart plugin_loader | revives Decky Loader's panel, which dies whenever Steam's CEF restarts and never comes back on its own |
systemctl restart --no-block couchside.service | lets an app-triggered update reload the new agent. Adds no privilege: that unit already runs the service user's own code as the service user |
| (root-owned journal wrapper) | see below |
Three more depend on what the box has. If a supported display manager is detected, the installer also grants systemctl restart <that manager> (the fix-a-black-screen rescue action) and a tee of one fixed file path, /etc/<manager>.conf.d/zzz-couchside-session.conf, which is how "boots into Game Mode / Desktop" is stored. On SDDM boxes a second tee, of the legacy zz- path, is granted so an updating box can blank its own stale pre-2.9.64 file. Both tee grants are root-owned file writes, and each names one exact path in the rule — this is not a grant of tee in general, and it cannot write anywhere else. A box with no supported manager gets none of the three: the agent degrades closed and the button never renders.
Note the journal grant carefully: it is for the wrapper, never for journalctl itself. The wrapper validates the unit and the line count and calls journalctl with a locked-down option set, because wildcard rule on would also permit / — turning "read the journal" into arbitrary file reads as root.
The couchside command — enabling extra features
The installer adds a couchside command to manage the box. Most of it is
everyday (couchside update, couchside status, couchside pair), but four
subcommands are opt-ins that are OFF by default — they widen what a paired
phone is allowed to do, so you turn them on only on the box, never from the
app. Each prints exactly what it grants before it does anything.
| Command | What it lets the app do | Privilege it grants |
|---|
couchside allow-updates on | Trigger a Couchside agent update from the app | none new — runs the signed installer the box already trusts |
couchside allow-system-updates on | Update your box's Flatpak apps and OS (SteamOS/Bazzite) from the app | passwordless sudo for one fixed command each — a root-owned wrapper that runs flatpak update --system / stages an rpm-ostree/steamos-update, and accepts no other arguments. Never a grant on flatpak/rpm-ostree themselves. |
couchside allow-launchers on | Create custom launchers from the app (not just trigger ones you defined) | none new — a launcher runs as your desktop user, never root |
couchside allow-decky on | Install, repair or remove Decky Loader on the box and install Decky store plugins from the app | passwordless sudo for two exact systemctl start argvs (the pinned couchside-decky-loader@install / @uninstall oneshot units) plus the /etc/couchside/allow-decky marker. The root wrapper those units run gets no grant of its own. This one does install software as root — Decky Loader runs as root from your home by design — which is why it is its own switch and prints the full story first. See Security model. |
Turn any of them off again with ... off, or check state with ... status.
An OS update stages for the next boot — the app shows "reboot to apply"
rather than pretending it finished. Nothing here can run an arbitrary command as
root: each grant is on a single fixed wrapper or an exact argv, validated with
visudo, and sorted last (zz-couchside-updates, zz-couchside-decky) so a
distro's wheel rule can't shadow it. Only allow-decky can install new
software, and only the one thing it names. An interactive install offers the
Decky opt-in once (default no); a detached, app-driven update never asks and
never enables it.
Full detail on why the grants are shaped this way is in the Security model
section above.
Uninstall
curl -fsSL https://couchside.tv/install.sh | bash -s -- --uninstall
That removes the service, sudoers rules, udev/modules-load drop-ins, the privileged helper and its units, the install dir (it asks before deleting the token), and the Decky Loader manager pieces if they were installed — the root wrapper /etc/couchside/couchside-decky-loader, the unit template [email protected], the allow-decky marker and declined stamp, the zz-couchside-decky grant, the run-state files under /run/couchside/decky-loader.*, and the user-side caches ~/.cache/couchside/decky-icons and ~/.cache/couchside/decky-job.json. Decky Loader itself and your plugins are left alone. To do it by hand:
sudo systemctl disable --now couchside.service
sudo rm -rf /etc/couchside /etc/sudoers.d/couchside ~/.local/opt/couchside
sudo rm -f /etc/udev/rules.d/99-couchside-uinput.rules \
/etc/modules-load.d/couchside-uinput.conf \
/etc/systemd/network/50-couchside-wol.link
sudo rm -f /etc/systemd/system/couchside.service && sudo systemctl daemon-reload
# SteamOS keep-list drop-in and the install manifest, if present
sudo rm -f /etc/atomic-update.conf.d/couchside.conf /var/lib/couchside/install-manifest
# Decky Loader manager pieces (agent 2.9.105+), if present; Decky itself is untouched
sudo rm -f /etc/sudoers.d/zz-couchside-decky \
/etc/systemd/system/[email protected] \
/run/couchside/decky-loader.lock /run/couchside/decky-loader.log \
/run/couchside/decky-loader.result
rm -rf ~/.cache/couchside/decky-icons ~/.cache/couchside/decky-job.json
sudo systemctl daemon-reload
Then delete the app from your phone.
Development
Start with CONTRIBUTING.md for setup, focused test commands and
review expectations. The code map shows the main components,
request flow and security boundaries without depending on source line numbers.
agent/: Linux service, privileged helper and platform ports.app/: Expo / React Native phone app, native modules and tests.- Decky integration lives in the separate
emerytech/couchside-decky repository.
protocol/, tests/, .github/workflows/: shared contracts, regression checks and delivery.
Use scripts/web-dev.sh for a local browser preview. Mock mode
is useful for UI work, but does not replace device tests or isolate filesystem
writes. The API reference is in agent/README.md.
Pricing & license
The service is free and open source. The app's source is public. The official app builds are a free 7-day trial, then a one-time unlock: $4.99 summer launch price, rising to $7.99 on September 1.
- Service, installer, brand, docs: MIT. Use them anywhere, for anything — including building your own client against the protocol. See LICENSE.
- The mobile app (
app/): source-available under the PolyForm Noncommercial License 1.0.0. Read it, audit it, npx expo run:ios / npx expo run:android it onto your own phone, and modify it for personal, noncommercial use. What you can't do is sell it or redistribute it commercially. See app/LICENSE. The trial gate ships in this public source; self-built personal copies without a store build are treated as unlocked by design, and that's fine.
- The official builds on the App Store and Google Play are free to download with everything unlocked for 7 days, then a one-time in-app unlock: $4.99 through the summer, rising to $7.99 on September 1. No subscription, no accounts. Unlock before September 1 to keep a permanent Early Adopter badge. You're paying for signed, notarized, auto-updating builds and a setup that goes from
curl to couch in under ten minutes. It's also the only funding this project has, so thank you.
© 2026 Taylor Emery (ETS3D LLC).
