Streaming with Moonlight

Streaming with Moonlight

CouchLiteOS streams games from your gaming PC with Moonlight. The gaming PC runs Sunshine (or NVIDIA GeForce Experience).

1. Prepare the gaming PC

1. Install and configure Sunshine using Sunshine's documentation.
2. Use wired gigabit Ethernet on both machines where you can.
3. Windows host: install ViGEmBus so the controller works in games.
4. For waking the PC from the couch, turn on Wake-on-LAN in its firmware and network adapter.

2. Pair

From the Setup Wizard's STREAMING PC step, or Settings > STREAMING > PAIR A GAMING PC (PAIR ANOTHER GAMING PC once one is paired):

1. Choose SEARCH THE NETWORK (RECOMMENDED). FIND GAMING PCS lists the PCs running Sunshine on your network.
2. Pick yours and type the PIN shown on CouchLiteOS into Sunshine's web page.
3. Not listed? The PC is off or asleep, Sunshine is not running, or it is on another network. Choose WAKE PC, SEARCH AGAIN, or ENTER ADDRESS MANUALLY (name or IPv4 address).

On a live USB without persistence the pairing is forgotten at power-off (Install).

3. Play

• GAMES on the home screen lists the games of your paired PC, the most recently played first, with their covers. Press A / Cross on a game: CouchLiteOS wakes the PC if needed and starts the stream. With no PC paired, GAMES offers ADD A GAMING PC; GAMING PCS at the end of GAMES pairs, wakes and manages them.
• Hold X / Triangle (or F10) on a game for its own STREAM SETTINGS, and Y / Square (or F9) to change its cover. See Game Covers and Stream Settings.
• MOONLIGHT in APPS opens Moonlight's own list of gaming PCs and apps. It wakes the default PC first; if the PC does not answer, Moonlight still opens and says why.
• The top of the home screen shows whether the PC is ONLINE, ASLEEP, NOT FOUND or has NO SUNSHINE running.
• During a stream Guide and the PlayStation touchpad go to the gaming PC. Hold Select + Start (View + Menu) for 1.5 s, or use another Home shortcut, to get back to CouchLiteOS without ending the stream; close Moonlight from ACTIVE APPLICATIONS. The quick menu shows the STREAM PRESET in use and has SHOW STATS.
• After the stream, Home comes back with the game you just played in focus.

In the classic interface, the top row STREAM PC NAME wakes the PC and starts the app chosen in Settings > STREAMING > APPLICATION.

Settings > STREAMING

Row	What it does
AUTO-STREAM AT STARTUP	Start streaming to the chosen PC whenever the box starts or wakes (after a 15-second countdown on wake)
PC / APPLICATION	Which paired PC and which Sunshine app (for example Desktop) auto-stream (and STREAM in the classic interface) use
WAKE PC	Send a Wake-on-LAN packet. Unavailable until Moonlight has seen the PC awake once.
OPTIMIZE STREAM SETTINGS	Measures the network for about ten seconds and sets Moonlight's resolution, frame rate and bitrate for your screen and network. Close Moonlight first. Games with their own STREAM SETTINGS keep those.
PAIR A / ANOTHER GAMING PC	Pair (above)
STREAM CHECK	Measures the path to the gaming PC for a few seconds and says GOOD, OK or POOR, with what to change (cable, Wi-Fi band and signal, SMOOTHER STREAM)
SMOOTHER STREAM (LOWER QUALITY ONE STEP)	Lowers the bitrate one step. To undo, run OPTIMIZE STREAM SETTINGS.
VIDEO DECODER FIRMWARE	Only on PCs using the open nouveau driver; see below

Good starting point: 1920x1080, 60 FPS, automatic codec, full screen. Then try 1080p120, 1440p60 and 4K60 if your screen and network allow. 4K60 is best effort. For one game only, use its STREAM SETTINGS (PERFORMANCE, BALANCED, QUALITY or CUSTOM).

Video decoding

Graphics	Decoding
Intel, AMD	Hardware (VA-API)
NVIDIA on the NVIDIA ISO	Hardware (NVDEC)
NVIDIA on the open nouveau driver (general ISO, Basic Graphics, Secure Boot on, older cards)	Software H.264 on the CPU. CouchLiteOS sets this automatically so Moonlight does not complain.

VIDEO DECODER FIRMWARE (experimental, older NVIDIA such as Kepler, for example the iMac Late 2013): downloads NVIDIA's 325.15 driver from nvidia.com (27 MB, checked against a fixed SHA-256), extracts only the video decoder firmware and keeps it on the disk or stick. CouchLiteOS cannot ship that firmware itself. Moonlight switches to hardware decoding only after the decoder was seen working; otherwise it stays on software.

Stream is black or stutters

See Troubleshooting. Usually a black stream comes from the gaming PC (no monitor attached, a Remote Desktop session holding the screen). For stutter, run STREAM CHECK, use a cable, then SMOOTHER STREAM.

Streaming away from home (Tailscale)

Tailscale is optional; local streaming never needs it.

1. On CouchLiteOS open Settings > TAILSCALE and scan the QR code with a trusted phone to sign in.
2. Install Tailscale on the gaming PC too, and allow Sunshine's ports on its Tailscale interface.
3. In Moonlight, add the PC by its Tailscale name or 100.x.y.z address (network search does not cross Tailscale).

Advanced: a host profile in /var/lib/couchliteos/config.ini lets CouchLiteOS try the LAN address first, then the Tailscale name, then the Tailscale IP:

[host:gaming-pc]
lan_address = 192.168.1.50
tailscale_hostname = gaming-pc.example-tailnet.ts.net
tailscale_ip = 100.64.10.20
address_mode = auto
app =

couchliteos-host-address shows the address chosen, and couchliteos-tailscale-diagnostics shows whether the connection is direct or relayed (relays are often too slow for games; lower the bitrate first). Never port-forward Sunshine to the internet. CouchLiteOS never enables subnet routes, exit nodes, Serve or Funnel. Tailscale SSH is off by default; it can be turned on with sudo couchliteos-tailscale ssh-enable and still needs a matching rule in your tailnet policy.