Configuration #

Docs · Getting started · Troubleshooting

Configure the current Windows Rust host in the Rubylight console, normally at https://localhost:47990. Open Settings and search by a setting's name or configuration key. Resolution, stream frame rate, bitrate and codec are normally chosen in the client.

Start with the defaults below. Settings imported from an older installation keep their saved values; upgrading does not reset them to these defaults.

Defaults worth knowing #

These are defaults for unset keys, not a list of values you must copy into a configuration file.

Capture and video #

Keep Capture method on Automatic and compute conversion enabled for normal use. On supported AMD hardware, the compute path lets capture and colour conversion run alongside graphics work. Unsupported textures can fall back to the graphics path. The internal wgc_compute_copy switch also defaults to true; it is primarily useful for controlled troubleshooting.

The installed service runs WGC through a helper in the signed-in user's session. WGC can fall back to DDX when unavailable. Selecting a particular capture method is useful when investigating a problem; check Logs to see which path actually opened.

H.264, HEVC and AV1 depend on the encoder and client. For hevc_mode and av1_mode, the choices are 0 Automatic, 1 Off, 2 SDR only and 3 SDR and HDR. Restart after changing advertised codec support. There is no 4:4:4 switch: the host offers 4:4:4 for a codec only when the startup check encodes it on a hardware encoder. AMD's encoder makes 4:2:0 only, so an AMD host offers 4:4:4 through PyroWave alone.

For native HDR, enable HDR in the client and use an HDR-capable display and encoder path. Leave Display HDR on Automatic so Rubylight can set the source display appropriately. 10-bit SDR instead of HDR (prefer_sdr_10bit, default false) deliberately keeps the stream in SDR; leave it off when you want HDR. RTX HDR is a separate SDR-to-HDR conversion feature, with its own hardware requirements.

PyroWave needs a compatible client and much more bandwidth than conventional codecs. Desktop and game test scenes on AMD give two warning levels. The floor warns about severe detail loss; the recommendation targets clean pictures in those tests. Passing the floor alone does not mean a clean picture.

These values are rounded up to whole Mbps. Below 1080p the floor/recommendation are 2.5/5 bits per pixel per frame; at 1080p and above they are 1.5/3.2. The smaller desktop's one-pixel text needed more bits per pixel. Rates scale with pixel count and frame rate within each band: halve them at 30 fps, double them at 120 fps. Other sizes are estimates; actual quality depends on text size, textures and the picture. The console stream card uses red below the floor and amber below the recommendation, and the log distinguishes both. The October 12, 2026 Rubylight 2.2.9 validation rechecked these budgets on synthetic desktop and game pictures; it measures decoded quality, not sustained network throughput. Original October 7 method and criteria.

Set the bitrate in Moonlight and leave network headroom for packet overhead and recovery data. The 4K60 recommendation needs more than gigabit Ethernet. Client and host limits still apply: stream setup allows up to 2 Gbps, while the client's runtime /bitrate endpoint caps changes at 500 Mbps. If the client or network cannot carry the recommended rate, use HEVC or AV1. Enabling PyroWave does not force ordinary Moonlight clients to use it. NVIDIA users should use Vibepollo.

A Rubylight client can change the stream's resolution and frame rate without reconnecting, for example when a foldable phone opens its inner screen. The encoder restarts at the new size with a keyframe and pacing follows the new rate; the PC's display keeps its mode and the picture is scaled to fit. stream_reconfigure (default true) turns this off for the host, a device or an app; clients that never ask are unaffected. Control messages describes the request.

VRR is client-negotiated. A VRR request can use a 1000 Hz virtual display when automatic virtual refresh is enabled. That is the host's virtual display rate, not a claim that your TV or monitor refreshes at 1000 Hz. Client and display support still matter.

Packet pacing limits video bursts. With pacing_max_bitrate_kbps = 0, H.264, HEVC and AV1 use twice the negotiated encoder bitrate when Windows identifies the host's route as Wi-Fi or mobile broadband, bounded to 1–800 Mbps. Ethernet, loopback, VPN, Tailscale and unknown routes retain the rc.19 default of 800 Mbps. A known physical Ethernet link caps that at 80% of its reported speed. For virtual Ethernet adapters such as Hyper-V vSwitches, the host tries to resolve the physical adapter through Windows' interface stack. Missing or ambiguous bindings keep the wired default. The host cannot detect a wireless client behind a wired access point from its own Ethernet route.

Set pacing_max_bitrate_kbps to a positive value in kbps to override the automatic policy, including for PyroWave. For example, 120000 paces at 120 Mbps. The existing floor of 110% of the stream bitrate still applies, and a known Ethernet link can lower the limit to 80% of link speed. This changes packet spacing, not the encoded bitrate; reconnect after saving. PyroWave's automatic policy retains 95% of a known Ethernet link, or 1.25 times its per-frame wire demand (at least 110% of the stream bitrate) on other routes, so its high-bandwidth intra frames are not restricted by the conventional-codec default. Measurements and pacing math.

Leave AMF's low-latency mode and AV1 latency mode on Driver default. In the October 12, 2026 Rubylight 2.2.9 property sweep, default ultra-low-latency usage already read back internal low latency for H.264/HEVC and AV1 latency mode 3 on the RX 7900 XT. Explicitly forcing the same settings produced similar timings across three runs, not exact equality or a demonstrated speedup. With Low latency or Transcoding usage, single auto/forced pairs changed the readbacks from off to on and showed mean reductions of 0.30-0.31 ms for HEVC and 1.01-1.37 ms for AV1. These are eight-second synthetic 1440p120/20 Mbps component tests, not full-stream latency measurements. The October 7 audit documents earlier measurements and the RX 9000 HEVC-freeze concern; forcing these settings remains opt-in.

Adaptive quantization (amd_vbaq) is off for H.264 and on for HEVC and AV1 when unset. In the October 12, 2026 Rubylight 2.2.9 settings comparison, explicitly turning H.264 AQ on reduced VMAF in all four cases: by 1.44 and 11.89 points on the two clips at 1440p120/20 Mbps, and by 0.06 and 0.41 at 50 Mbps. Turning AQ off gave mixed HEVC results, while AV1 VMAF rose in all 14 tested cases by 0.0009-0.2301 points in SDR and 0.0051-0.4822 in converted HDR. Those small AV1 gains do not establish a universal visual-quality benefit; the HDR scores also use converted SDR footage. Set AQ to On or Off to compare your own content, or Driver default to leave it to the driver. The October 8 findings remain a separate historical result.

The current default-quality results cover 32 cases; the settings comparison adds 116 alternatives for quality preset, rate control, AQ, usage and high-motion boost. Each case encoded and scored exactly 180 frames, with no minimum VMAF pass threshold. CBR increased p99 frame size in every tested case; its score changes depended on codec and content. Ten high-motion-boost requests completed but lacked effective-setting readback, so their application is unverified. Encode-time deltas use earlier baselines rather than randomized matched trials. HDR rows convert SDR footage with 203-nit white and do not establish native-HDR perceptual quality.

Leave split-frame encoding on Automatic. AMF can split one HEVC or AV1 frame across a Radeon's two encoder engines (amd_split_frame), and the driver decides whether it does. Automatic asks for it only when the GPU has two engines and the driver has it off; On asks whenever there are two engines, and Off disables the property. In the October 12, 2026 Rubylight 2.2.9 sweep, RX 7900 XT readbacks were 1 for Automatic/On and 0 for Off. Identical-input synthetic throughput was similar: for example, two-run means for 4K HEVC were 197.32 / 197.37 / 197.36 FPS respectively. This does not mean every frame had identical timing or prove how the driver used its engines. The sweep completed 708/720 calls; twelve pre-analysis cases failed and remain documented. It did not assess decoded quality. H.264 has no split-frame property; single-engine GPUs get no property write. Historical October 7 measurements remain separate.

AMF rate-control limits are optional. In Settings → Encoders → AMD AMF, the advanced controls below use the client's requested bitrate and frame rate. All default to 0, which leaves the corresponding property to the driver. Reconnect after saving. An unsupported explicit request is reported as an AMF setting error; the effective values appear in the AMF encoder settings log line.

These are encoder bit budgets, not extra queued frames or packet-pacing settings. A smaller budget trades picture quality for smaller frames. Intra refresh remains client-negotiated and does not replace an explicit recovery-keyframe request. See the rate-control measurements before changing these controls. NVIDIA users should use Vibepollo.

amd_rc remains vbr_latency by default. For an affected AMD stream, amd_max_frame_size=1 or 2 lets you compare smaller recovery frames against picture quality; 0 restores the driver default. These caps cut the largest recovery frames sharply. They are off by default because they trade picture quality for smaller frames.

Displays and RTSS #

Under Settings → Display, select a physical display or choose a virtual display per device/shared by all devices. Exclusive switches other monitors off; choose Extended to keep the existing desktop active. The primary and isolated variants control where the virtual display sits in that desktop.

Resolution and refresh policies default to auto (dd_resolution_option, dd_refresh_rate_option). Virtual refresh follows the frame-limiting policy unless a manual or device display mode overrides it. To leave a physical monitor's resolution, refresh and HDR unchanged, select Disabled for dd_configuration_option.

A disconnect can leave the app and its display available for reconnection. Enable dd_config_revert_on_disconnect if you want the display configuration restored on disconnect; it defaults to false. Without it, a disconnected device's display is kept while its app runs for dd_paused_virtual_display_timeout_secs (default 7200 seconds; 0 keeps it until the app closes). A client that sends nothing for ping_timeout (default 10000 ms) ends its stream. Maintenance provides display restoration and saved-baseline controls.

Under Settings → Frame limiting:

• Keep Limiter on Automatic, or select RTSS. Set RTSS folder (rtss_install_path) only if detection fails; an empty value searches Program Files.
• Rubylight starts RTSS when a limit is needed and restores the previous limit after disconnect. If RTSS requires administrator access, the installed service can use the signed-in administrator's token; otherwise start RTSS with the required access yourself.
• Frame limit (frame_limiter_fps_limit) defaults to 0, meaning the stream rate. RTSS preserves fractional rates such as 59.94 FPS.
• Virtual display refresh offers 2× (legacy), 4× (enabled), 1000 Hz (vrr) or Off (disabled). Turning Limit every stream off does not disable the automatic virtual-display limit. Choose Limiter → None (frame_limiter_provider = none) to disable all limiting.

Controllers #

Settings → Input → Controller type controls which virtual controller games see. Every pad comes from the VHF gamepad driver that the installer brings; no other driver is needed.

gamepad = auto matches each client's controller. PlayStation clients get a DualSense, the only pad with adaptive triggers; it also carries motion, battery, touchpad, lightbar and rumble. A game's trigger effects reach the player only if the client forwards them to a real DualSense. Nintendo clients get a Switch Pro. Other clients get an Xbox Series pad, or a DualSense when they have motion sensors or a touchpad and motion_as_ds4 or touchpad_as_ds4 is enabled. Both preferences default to enabled, so a Steam Deck reporting motion gets a DualSense.

vhf_xbox, vhf_xbox_one, vhf_ds4, vhf_ds5 and vhf_switch give every client that pad: vhf_ds5 a DualSense, vhf_ds4 a DualShock 4 without adaptive triggers. Logs name the profile for each connected controller.

Earlier releases also offered Xbox 360 (x360) and DualShock 4 (ds4) through ViGEmBus. Since rc.25 Rubylight changes those settings to vhf_xbox_one and vhf_ds4 when it loads them, in the host configuration, app and device overrides, and configurations imported from Sunshine, Apollo or Vibepollo. An installed ViGEmBus is no longer used and can be uninstalled.

Steam Deck #

A Steam Deck can reach the host as a real Steam Deck controller: Rubylight serves the Deck's own USB controller (Valve 28de:1205) over USB/IP on the host's loopback address, and usbip-win2 attaches it with its signed driver, so Windows sees a Steam Deck plugged into a USB port. Steam on the host then recognises a Steam Deck and applies the Deck's Steam Input layout, with both trackpads, the gyro, the back grips (L4, R4, L5, R5), the Steam and "…" buttons and rumble. Games see whatever Steam Input makes of it, as on a Deck.

• Settings → Input → Steam Deck and back grips → Steam Deck controller (steam_deck_controller): Automatic (auto, the default) attaches a Steam Deck when usbip-win2 is installed and Steam is running on the host when the controller connects; Steam Deck (steam_deck) attaches one whenever usbip-win2 is installed, even without Steam, where only SDL-based games see it; Virtual pad (virtual_pad) always uses the virtual DualSense or Xbox pad below.
• Install usbip-win2 on the host from its releases (Windows 10 1903 or later). Its setup installs a driver and restarts the USB hubs once, so devices on them reconnect; it recommends a restore point first. Rubylight looks for usbip.exe in C:\Program Files\USBip and on PATH. Nothing listens beyond 127.0.0.1.
• If usbip-win2 is missing or the attach fails, the Deck falls back to the virtual pad, and the stream card says why when Steam Deck was chosen or an attach failed.

Moonlight passes on the Deck's own controls only when Steam Input is off for Moonlight on the Deck. With it on, Steam on the Deck turns the controls into a virtual pad first: the host still gets a Steam Deck with the buttons, sticks and triggers, but no gyro, trackpads or back grips, because Moonlight never receives them. On the Deck, open Moonlight's controller settings in Steam, choose to disable Steam Input, and reconnect. If the paired device's name says Steam Deck (SteamOS calls it steamdeck) and its controller arrives without a gyro, the stream card says this.

Moonlight sends trackpad touches from builds whose SDL reads the Deck's trackpads (SDL 3).

With the virtual pad (no usbip-win2, or Virtual pad), Moonlight's Steam controller with gyro gets a DualSense:

• Gyro and accelerometer are the pad's motion sensors.
• Trackpads share the pad's one touch surface: the left trackpad is its left half and the right trackpad its right half. Clicking the right trackpad is the touchpad click.
• Back grips (L4, R4, L5, R5): the virtual pads have no back buttons, so each grip presses what Settings → Input → Steam Deck and back grips sets for it: a face button, bumper, a fully pulled trigger, a stick click, Back, Start, Guide, a d-pad direction, the touchpad click or Share/Mute (back_grip_l4, back_grip_r4, back_grip_l5, back_grip_r5; values a, b, x, y, lb, rb, lt, rt, l3, r3, back, start, guide, dpad_up, dpad_down, dpad_left, dpad_right, touchpad, misc). They default to nothing, and pressing an unmapped grip shows a hint on the stream card. The same settings map an Xbox Elite's paddles (P1 is R4, P3 is L4, P2 is R5, P4 is L5) and a DualSense Edge's back buttons.
• Steam and "…" buttons become the PS button and the DualSense's mute button (the touchpad click on a DualShock 4), when Steam on the Deck lets them through to Moonlight.
• Rumble and battery level are passed on.

Setting motion_as_ds4 and touchpad_as_ds4 both off keeps a Deck's virtual pad an Xbox pad, without its gyro and trackpads.

MoonDeck #

MoonDeck works with Rubylight. It launches Steam games from the Steam Deck through Moonlight, with MoonDeck Buddy managing Steam on the host. You only need one host app for MoonDeck; you do not need to add each Steam game to Rubylight.

1. Install MoonDeck on the Steam Deck and MoonDeck Buddy on the Windows host. Keep Buddy running, pair it through MoonDeck's settings, and pair Moonlight with Rubylight.
2. In Rubylight's Library, add an app with Name set to MoonDeckStream and Command pointing to "<BuddyInstallDirectory>\bin\MoonDeckStream.exe". Replace <BuddyInstallDirectory> with Buddy's actual installation folder and keep the quotes around the path.
3. Under the app's Behavior, turn off Keep the stream when a launcher exits within 5 seconds (auto-detach) and save. Wait for every process the app starts (wait-all) can stay enabled. These correspond to the options in MoonDeck's host setup guide.
4. In Buddy's settings.json, next to its executable on Windows, set sunshine_apps_filepath to the full path of Rubylight's apps.json, then restart Buddy. For a standard installed service, the JSON entry is "sunshine_apps_filepath": "C:\\ProgramData\\Butterpollo\\config\\apps.json". For a portable or custom profile, use apps.json in the active profile folder, unless file_apps points elsewhere. Buddy's automatic lookup looks for Sunshine and can otherwise find the wrong installation or no app list. See Sunshine apps filepath in Buddy configuration.
5. Select the Rubylight host in MoonDeck and use MoonDeckStream as its host app. The name must match the app saved in Rubylight.

Controls with MoonDeck #

Moonlight carries controller, keyboard and mouse input to Rubylight. MoonDeck launches a separate Steam shortcut for the stream, so configure the running MoonDeck shortcut's controller layout on the Deck; settings on the standalone Moonlight shortcut do not configure it.

• Deck-side layouts. Keep Steam Input enabled on the Deck for that shortcut and choose a gamepad layout, or edit it for the game. Map L4/R4/L5/R5 to buttons or keys, and map gyro or trackpads to mouse or stick movement as needed. Moonlight sends the resulting inputs; these mappings do not send the raw motion sensors, separate trackpad touches or back-grip identities to the host.
• Community layouts. In MoonDeck's Game Session settings, enable Automatic title switch to AppId (MoonDeck app only) to access the game's community controller layouts. You can also toggle AppId as game title in MoonDeck's right-side quick-access panel during a stream. With this enabled, use Exit MoonDeck in that panel to stop the session; Steam's left-side exit button does not work. Opening side panels can temporarily lose controller focus. These options and limitations are described in MoonDeck's Game Session settings.
• External controllers. MoonDeck's Game Session → Selected Steam Input option → Disable Steam Input lets Moonlight see the actual external controller, including supported motion input. MoonDeck documents this option for external controllers; do not assume it disables Steam Input for the Deck's built-in controls.

For host-side Steam Input with the Deck's own controls, follow the Steam Deck controller setup: install usbip-win2 on the host, use a client that exposes the required controls, and disable client-side Steam Input for the shortcut MoonDeck actually launches. Start Steam on the host before connecting when using Steam Deck controller → Automatic. This mode depends on the client sending raw controls; a working button layout alone does not confirm gyro, trackpad or back-grip passthrough.

If controls do nothing, check the paired device's Controllers permission under Devices and the console's stream warnings. Keyboard and mouse mappings also need their respective device permissions. See input troubleshooting for permissions and the VHF gamepad driver.

Settings for one app or device #

Edit an app in Library or a paired device in Devices to set its display, HDR and other overrides. Leave an override unset to inherit the host configuration.

For general configuration overrides, Rubylight applies host settings → device overrides → app overrides. Only supported stream, input, display and encoder keys are accepted; host-wide network, identity and path settings cannot be overridden per stream.

Display selection has dedicated rules: a device's explicit virtual-display mode takes priority over the app's mode, and its display mode (WIDTHxHEIGHTxREFRESH) overrides the host's resolution/refresh policy. This does not change the frame rate requested for the encoded stream.

Display choice from the client #

A client can choose, for one stream, what the PC's displays do. Rubylight Android sets it per PC under This PC → Display on the PC. The client sends hostDisplay with /launch or /resume:

The choice comes before the host, device and app settings for virtual display mode and layout, including a device's Always use a virtual display. Two cases still get a virtual display after physical: a PC with no active display, and an output that names the virtual display itself. A virtual display needs its driver; without it the stream shows the physical display with a warning, as for any other request. When another stream already holds the display layout, a second stream joins that layout. The layout from before the stream comes back when the stream ends, as with the host's own settings. A display kept for reconnection is reused only when the next launch asks for the same choice, or asks for nothing. Remote Monitor and Remote Input ignore the parameter. Older Rubylight hosts and other hosts ignore it, so Rubylight Android also sends virtualDisplay=1 with the virtual choices, which those hosts honour where they support a virtual display.

Save, reconnect and restart #

Select Save changes to write the configuration. Edits are not saved merely by changing a control or switching categories. Saved stream settings are read when a new stream starts; an existing stream generally keeps its current configuration.

The console shows “Saved. Some changes apply after the host restarts.” Startup settings, including network listeners and advertised codec capabilities, need a restart. Use Restart now after disconnecting: restarting the host disconnects active streams.

For file-based configuration, the file is still named sunshine.conf for compatibility:

The format is key = value, one setting per line. Stop the host before editing files directly, then start it again to load them. Prefer the console for ordinary changes; old or unknown keys can be preserved without being implemented by the Rust host.

Multiple instances #

Give each instance its own profile folder and base port. An explicit --config-dir takes precedence over the portable defaults. From the extracted package, run these commands in separate PowerShell windows, one in each intended Windows session:

.\butterpollo.exe --config-dir C:\RubylightProfiles\Seat1 --port 48123
.\butterpollo.exe --config-dir C:\RubylightProfiles\Seat2 --port 48323

The consoles are at https://localhost:48124 and https://localhost:48324. These base ports also keep the instances' streaming ports separate from each other and from the default installed host. To make the port choice persist when using Start Rubylight.exe, save port = 48123 or port = 48323 in the corresponding profile's sunshine.conf. The launcher accepts --config-dir; --port is a host option.

For copied portable packages, create a separate config folder beside each copy of butterpollo.exe and set a different port in each folder's sunshine.conf before launching. Automatic selection of this adjacent folder requires 2.2.6 or later; older packages need an explicit --config-dir. Without an adjacent folder or explicit path, copies running as the same account share the per-user default, including SYSTEM's systemprofile location. Start with fresh profiles for independent identities and pair each instance separately; copying a populated profile also copies its identity and paired devices.

For multiseat use, launch each process in its intended Windows session through your multiseat software, using that session's SYSTEM token if required by your setup. The installer continues to manage one Windows service. Separate-profile startup has been smoke-tested with two simultaneous hosts; simultaneous streaming from different Windows users still needs validation.

Updates #

Automatic checking is enabled; automatic installation is not. Use Maintenance to check manually or start an offered update. Enable Include pre-releases if you want release candidates.

If you opt into Install updates automatically, the installed Windows service waits for one minute without active streams, pending connections, remote-monitor sessions or running host apps. The updater validates the selected installer against the release's size and SHA-256. Portable installations use the release download page instead.

Set update_check_interval = 0 to disable scheduled checks; manual checks remain available.

Further reference #

• Features
• Measured performance and testing conditions
• Console settings definitions, including video, display and general settings
• Configuration parser and allowed overrides
• Historical C++ configuration reference — preserved for older installations; its defaults and platform advice do not describe the current Rust host.