Getting started #

Documentation · Configuration · Troubleshooting

Rubylight is a Windows x64 streaming host written in Rust, with a GPU path tuned and measured on AMD Radeon. Moonlight runs on the device you play from. Start with one client and a 1080p60 SDR stream, then add HDR, higher frame rates or a virtual display.

On this page: Before you start · Install · Open the console · Pair Moonlight · Stream formats · Displays and updates · Import a profile · Upgrading

Before you start #

First stream: Install → open the console → pair Moonlight → launch Desktop at 1080p60, HDR off. Once picture, sound and input work, choose your final codec and display settings.

Already using Rubylight? Go straight to Upgrading. Moving a portable Apollo or Vibepollo profile? Read Bring an existing profile before the first launch.

Install or run portable #

Download the Windows package from Rubylight Releases. For 2.2.10, choose:

Releases up to 2.0.1 also list a butterpollo-setup-<version>.exe. It is the same file as rubylight-setup-<version>.exe under the name Rubylight had before; download either. Butterpollo and Rubylight are one product, so there is no separate Butterpollo download, and installing over a Butterpollo host keeps its settings, paired devices and apps.

The installer sets up the host, the Windows service, the virtual display driver and, unless you untick it, the virtual gamepad driver that every emulated controller uses. An upgrade preserves the existing Rubylight settings and paired devices and can migrate a detected Vibepollo installation.

• Install folder. A new installation goes to C:\Program Files\Rubylight; Change folder… in the setup window picks another folder on a drive of this PC. Picking a folder that already holds other files installs into a Rubylight folder inside it. A folder outside Program Files gets the same permissions Program Files has: only administrators can change the programs the service runs. An installed Rubylight is updated in its own folder. To move it, uninstall it (settings and paired devices stay in %PROGRAMDATA%\Butterpollo) and install again in the new folder.
• Installing during a stream. You can run the installer from inside a stream, for example from a PC on another floor. Setup says that Rubylight is streaming; Install then ends the stream and closes games started from Moonlight, installs, and starts Rubylight again. Connect again when setup has finished (16 seconds on the RX 7900 XT test host); the setup window shows the result on the host's desktop. Maintenance → Updates → Install now does the same from the console.
• Quiet installs (rubylight-setup-<version>.exe --quiet, for scripts and remote shells) refuse to stop a stream unless you add --end-streams. --install-dir <folder> picks the folder for a new installation.

Portable mode does not install a service. Virtual displays and emulated controllers need their Windows drivers; use the installed service for the bundled virtual-display driver's service access. Keep the extracted libraries and assets folder beside the executables.

Run one streaming host on the default ports. If Sunshine, Apollo or Vibepollo is already serving those ports, close that host before starting the portable copy, or use separate profiles and ports.

Open the console #

The launcher opens https://localhost:47990 on the host PC. A custom base port changes the console port too. The console uses a local self-signed certificate, so the browser may show a certificate warning; check that you are opening your own host's address. Create the local administrator account if prompted; initial account setup must happen on the host PC. After an import from Apollo, Vibepollo or Sunshine, sign in with that host's console username and password.

To set a new sign-in, open PowerShell as administrator on the host PC and run the host program with --creds (the sign-in page on the host PC shows the full path):

& "C:\Program Files\Rubylight\butterpollo.exe" --creds NAME PASSWORD

Use a password of at least 8 characters, then sign in with the new name and password. Signed-in browsers sign in again. An installation upgraded from Butterpollo keeps its original install folder.

On Overview, check Host readiness for the video encoder, virtual display, audio and screen capture. An available encoder and an active physical display are enough for the first desktop stream. A virtual display showing Off is expected when you are streaming a physical monitor.

A fresh Windows 11 configuration selects a virtual display for each device; Windows 10 defaults to a physical monitor. For a portable first run with a monitor, select Settings → Display → Virtual display: Off, stream a monitor. If you use the installed virtual display, the default Exclusive layout turns the other monitors off during the stream; choose Extended to keep them active.

For a fresh configuration, leave Settings → Video → Capture method on Automatic. This prefers Windows Graphics Capture (WGC), with Desktop Duplication as its startup fallback. Copy and convert on a compute queue is enabled by default on the supported AMD path. Imported explicit capture choices remain in effect.

Pair Moonlight and start Desktop #

1. Open Moonlight on a device on the same local network. Select the host, or add the PC by its local IP address if discovery does not find it.
2. Moonlight displays a four-digit PIN. In Rubylight's Devices page, enter that PIN for the pending device and select Pair.
3. Wait for pairing to finish on the client. The device then appears under Paired devices.
4. Set Moonlight to 1920×1080 at 60 FPS, with HDR off for this first check. Use H.264, or HEVC if the client supports hardware decoding.
5. Launch Desktop. Check moving windows, sound and input before increasing resolution, frame rate or bitrate.

You are ready to tune the stream when the desktop moves smoothly, audio plays and your input reaches the PC. Increase resolution and frame rate in the client, then enable HDR if both the client and captured display support it. The Overview stream card shows what was actually negotiated.

If the host is missing, start with discovery and pairing. If Desktop opens to a black picture, check capture and displays.

If pairing succeeds but launching is denied, check the device's enabled state and List apps, View streams and Launch apps permissions in Devices → Edit.

Choose your stream format #

H.264, HEVC and AV1 use the standard Moonlight streaming path; the formats available to you depend on the host encoder, client software and decoder. PyroWave uses a separate codec path and needs substantially more bandwidth; its client can calibrate the connection before streaming.

PyroWave's recommended rates, from desktop and game test scenes on AMD, are 277 Mbps at 720p60, 399 Mbps at 1080p60 and 1593 Mbps at 4K60. Quality depends on the picture. The stream card warns below those rates and uses a stronger warning below the severe-loss floors of 139, 187 and 747 Mbps respectively. A rate above the floor alone is not a clean-picture target. Leave headroom for packet overhead and recovery data; 4K60 needs more than gigabit Ethernet. Use HEVC or AV1 when the client or network cannot carry the rate. Measurements and limits. NVIDIA users should use Vibepollo.

Moonlight's YUV 4:4:4 option needs an encoder that produces 4:4:4. AMD Radeon GPUs encode H.264, HEVC and AV1 in 4:2:0 only, so with an AMD host Moonlight streams 4:2:0; Moonlight warns that the host doesn't support YUV 4:4:4. On AMD, PyroWave is the way to get full-resolution chroma, in SDR and in 10-bit HDR. Native NVENC streams 4:4:4 on NVIDIA GPUs that support it.

For HDR, enable HDR in the client and confirm that the streamed display supports and enables HDR in Windows. In Settings → HDR, Display HDR: Match the stream and HDR request: Follow the device are the normal starting choices. A forced display HDR setting does not change an SDR stream into an HDR stream. Enable the game's own HDR mode when available.

The Overview stream card shows the negotiated codec and an HDR badge. Check the picture on the actual client display as well. The published native HDR tests verify captured and decoded pixels; they do not calibrate a TV or establish every client's HDR rendering. See HDR troubleshooting.

Virtual displays and updates #

In Settings → Display, select Virtual display: One for each device or One shared by all devices when you want a host-created screen. Choose Extended to add it beside the physical monitors; other layouts can make it primary or disable other displays. Per-app and per-device overrides can change the effective choice. The configuration guide explains those policies.

Updates notify you first. Maintenance → Updates offers Check now and, for the installed service, Install when idle and Install now; the tray menu also has Check for updates. Settings → General → Install updates automatically is off by default. Enable Include pre-releases to receive release candidates.

Install when idle and automatic updates wait for streams, pending connections, remote monitors and host apps to stop, then for one minute of idle time. A disconnected Desktop session can still have an app open: quit it from Moonlight or the console if an update stays queued. Install now downloads and installs right away, even while you stream: the stream ends and games started from Moonlight close while Rubylight restarts, and you connect again once it is back. Portable users download the new ZIP from the release page.

Bring an existing profile #

On the first portable launch, Yes in the import prompt copies an existing Vibepollo or Apollo profile. Select the folder containing sunshine.conf, or the installation folder containing config\sunshine.conf. No starts a fresh profile.

Import brings across settings, paired devices, identity, the console sign-in, the app library and covers. The original profile remains in place. The destination must be empty; Rubylight refuses to overwrite a populated profile. The prompt appears only when the portable profile has not already been created.

The default profiles are separate:

Opening the launcher again returns to the running profile's console. When launched from the installed package, it uses that package's Windows service profile. An explicit --config-dir selects another profile; see multiple instances for examples and release availability.

Upgrading #

• Installing ends streams and closes host-launched apps. The setup window warns first when Rubylight reports a stream; a quiet setup refuses unless given --end-streams. Vibepollo, Apollo and Sunshine cannot report this, so setup stops them without checking.
• Back up the whole profile folder from the table above (or the previous host's config folder). Include sunshine.conf, apps.json, covers, both identity files in credentials, sunshine_state.json, sunshine_credentials.json if present, and vibeshine_state.json. Also back up files named by custom paths in the configuration. Keep this backup private: it contains credentials and device certificates.
• Run the new installer, or use Maintenance → Updates → Install when idle or Install now. Settings, unknown configuration keys, paired devices, credentials, apps, device/display settings and saved session data stay in the profile. Active streams do not survive a restart. The service and web console use the new package; installed drivers remain available. Legacy AMD encoder names such as amdvce_experimental still select AMF. A saved Xbox 360 or DualShock 4 (ViGEmBus) controller type from an earlier version loads as the VHF Xbox One or DualShock 4 pad; an installed ViGEmBus is no longer used.
• For a portable update, close the portable host and extract the complete new ZIP into a separate folder. The launcher reuses %LOCALAPPDATA%\ButterpolloRust\config by default. If you use an adjacent config folder, copy that whole folder beside the new executable; if you use --config-dir, keep passing the same path. Keep the old ZIP and your profile backup until the new version works. Portable mode does not install a service or drivers. Avoid opening an older ZIP against a newer profile.
• From Butterpollo. Rubylight was called Butterpollo until rc.29. Upgrading renames what Windows shows (Start menu, Apps, the service's display name and the firewall rule) and keeps everything else where it was: the install folder, the ApolloService service, the profile folders above and the file names, such as butterpollo.exe. The launcher in the package is now Start Rubylight.exe; an update replaces the old Start Butterpollo.exe and the Start menu entry follows it. New installs go to C:\Program Files\Rubylight.
• If setup cannot identify one source profile, or Rubylight already has settings alongside another host's profile, resolve that choice before removing either host. Imports preserve recognized files and unknown fields; old logs and oversized or linked optional files can be skipped, so keep the original backup.
• Check that the console opens, existing clients connect, apps and covers appear, and display/controller settings still work. Restart Playnite if its connector was updated. If an update fails, keep the profile's updates folder and update-result.json for recovery. Installer downgrades are refused. Normal uninstall keeps the profile and drivers; factory reset and remove drivers explicitly delete them.

For everything Rubylight does and how fast it does it, see Features and Performance.