# CouchRelay for Decky Loader

Join a friend's shared screen from Gaming Mode on a handheld (SteamOS, Bazzite, CachyOS
Handheld) and play with your own controls, or share the handheld's screen with friends. Friends
use the CouchRelay app on Windows or this plugin.

CouchRelay is beta software: it works well on the devices it has been tested on, but expect rough
edges on others. The plugin tells you when an update is ready.

## Join a friend

1. Open the Quick Access menu (`…` button) → CouchRelay.
2. Pick a recent host, or type the address your friend gave you.
3. The first time, enter the PIN shown on their screen.
4. Select **Join**. The stream opens like a game. To end it, open the Quick Access menu →
   CouchRelay → **End stream** (or quit it from the Steam menu).

Join settings apply when a stream starts. **Optimize automatically** (the default) adapts the
quality to your connection; **Favor** chooses what it keeps first: frame rate (as smooth as your
screen allows, the default) or quality (at most 60 fps, for a sharper picture).

## Share this handheld

Select **Share this handheld** and give your friend the address and PIN it shows. When they have
typed it, a notification asks you to allow their device: press **···**, open CouchRelay and select
**Allow** (or turn on **Allow new devices without asking**). Friends on your
home network or a VPN need nothing else; over the internet without a VPN,
turn on **Open ports with UPnP** before sharing, or forward UDP port 47910 on your router to the
handheld. **Stay awake while sharing** keeps the
handheld from sleeping until you stop sharing, so friends can join later; with it on, **Keep the
screen dark** and **Keep the speakers quiet** dim the screen and mute the speakers after a minute
without using the handheld's controls (friends still see and hear the game).

## What the plugin does on your handheld

- Settings and pairings live in `~/.local/share/CouchRelay`. Joining adds a non-Steam
  shortcut called "CouchRelay", so Gaming Mode shows the stream and Steam Input maps your
  controls.
- The plugin runs with administrator rights for a few jobs a stream needs, all undone when the
  stream or sharing ends: Wi-Fi power saving is turned off and Wi-Fi stays on its current access
  point while a stream runs, the handheld is kept awake, and with the sharing options on, the
  screen brightness and volume are lowered.
- While sharing, friends' controllers become virtual controllers on the handheld.
- It connects only to the friends you share with or join. Once a day it also checks CouchRelay's
  website for a new version (a small file; nothing about you is sent), and offers it in the panel
  under **Updates**, where the check can be turned off. Installing an update restarts Decky.

## Removing

In the panel: **Remove** → **Remove from this handheld** removes the settings, pairings and the
shortcut. Then uninstall the plugin in Decky's settings.

## Licence

CouchRelay is free for noncommercial use under the PolyForm Strict License 1.0.0 (`LICENSE`,
`NOTICE.md`). It ships open-source software under its own licences: see **About** →
**Licences** in the panel, or the `licences` folder.