nix-config-ryan4yin/hosts/idols-ai/VR.md

Quest 3 PC VR on idols-ai

WiVRn streams PC VR games to Quest 3. It supplies the OpenXR runtime; xrizer translates OpenVR games. This host uses the server and command-line tools without the Dashboard. SteamVR does not need to run, but compatibility still depends on the game and translation layer.

First activation and persistence

Run just niri on idols-ai. Log out and back in so Steam sees PRESSURE_VESSEL_IMPORT_OPENXR_1_RUNTIMES=1. That variable is what makes pressure-vessel mount WiVRn's $XDG_RUNTIME_DIR/wivrn/comp_ipc socket into a game's container; without it the game's OpenXR client fails with ERROR_RUNTIME_UNAVAILABLE and the headset stays black.

The root filesystem is a 4 GiB tmpfs. These directories are preserved with mode 0700:

• ~/.config/wivrn/: server settings, paired headset public keys and discovery cookie.
• ~/.android/: ADB host keys, so USB authorization survives a reboot.

Before the first activation, migrate any existing directories to their matching locations under /persistent/home/<user>/. Stop WiVRn first. If both locations contain data, reconcile them before activating; do not overwrite existing pairing state or ADB keys. Do not display or upload ADB private keys, or copy them into this repository.

OpenXR/OpenVR runtime pointers and sockets remain temporary. WiVRn switches runtime pointers while a headset is connected and restores previous configuration when it disconnects. Do not manage these pointers as read-only Home Manager files, persist IPC sockets, or delete existing runtime configurations blindly.

Wireless connection and pairing

1. Connect the PC by Ethernet and Quest 3 to the trusted home LAN (192.168.5.0/24). Prefer 5 GHz or 6 GHz Wi-Fi near the access point. Guest Wi-Fi or client isolation can block discovery and streaming.

2. Install the WiVRn 26.9 client on the headset: the Meta Store build is packaged as org.meumeu.wivrn, the GitHub release APK as org.meumeu.wivrn.github. Client and server versions must match; check the installed server with wivrn-server --version after updates.

3. The server does not start automatically at login or boot. From this repository on idols-ai, start it when you want to use VR:

   just vr
   just vr-status
   

   just vr-stop stops it again. Starting the service does not enable it for future logins.

4. Allow a new headset to pair for two minutes:

   wivrnctl pair --duration 2
   

   This prints a PIN. Open WiVRn on the headset, connect to ai, and enter the PIN. If discovery fails, enter 192.168.5.100 manually. Reconnection after pairing does not require running this command again.

5. Audio follows the headset: WiVRn's wivrn.sink and wivrn.source exist only while a headset is connected, and a WirePlumber hook in ai/vr.nix makes them the defaults for exactly that time; playing streams follow. Your own default devices stay saved and return when the headset disconnects. Check with pactl get-default-sink and pactl get-default-source.

Manage paired headsets with wivrnctl list-paired, wivrnctl rename, or wivrnctl unpair. Consult wivrnctl --help and the subcommand's --help for arguments.

Service, settings and logs

Manage the server through systemd so starts retain the CAP_SYS_NICE wrapper:

systemctl --user restart wivrn
just vr-stop
just vr-status
journalctl --user -u wivrn -b -n 100 --no-pager
just vr-logs

Service logs use the host's existing persistent journal. There is no separate Dashboard log folder or log exporter. For server settings, edit ~/.config/wivrn/config.json following the WiVRn 26.9 configuration schema, then restart the service. The NixOS module also supports declarative server configuration; an enabled declarative config takes precedence over the user file. Headset-side settings remain available in the headset application.

Games and the RTX 4090

The RTX 4090 is the only GPU on this host, so the WiVRn server, the compositor and the game land on the same card by themselves.

That is not how it used to be. While ai ran the Z890 board, its Arrow Lake iGPU did the desktop rendering under PRIME offload, and a game left on the iGPU while the server ran on the dGPU failed with vkAllocateMemory: VK_ERROR_OUT_OF_DEVICE_MEMORY and xrt_comp_create_swapchain failed in journalctl --user -u wivrn, followed by an xrizer panic that killed the game. The fix then was the variables below, written out as Steam launch options because Steam runs inside a bubblewrap sandbox that does not mount /run, so it cannot see /run/current-system/sw/bin/nvidia-offload:

__NV_PRIME_RENDER_OFFLOAD=1 __NV_PRIME_RENDER_OFFLOAD_PROVIDER=NVIDIA-G0 __GLX_VENDOR_LIBRARY_NAME=nvidia __VK_LAYER_NV_optimus=NVIDIA_only %command%

It mattered for headset-launched games too: WiVRn starts applications in separate systemd units, and an already running Steam client keeps its own environment. Re-add those variables only if a second GPU comes back. Select a Proton version according to the game's compatibility reports; GE-Proton or DW-Proton alone does not guarantee VR compatibility.

USB connection

Enable Quest developer mode, connect a data-capable USB cable, and accept the headset's USB debugging authorization prompt. ADB is already installed in the desktop profile. The current systemd handles USB access for the active local session. Developer mode is needed for USB or sideloading, not for the Meta Store wireless workflow.

For sideloading, download the matching official APK and use adb install -r <apk-path>. The GitHub release APK is packaged as org.meumeu.wivrn.github, the Meta Store build as org.meumeu.wivrn; pass the package you actually installed.

Pair over Wi-Fi first. For an already paired headset with the GitHub APK installed:

adb devices
adb reverse tcp:9757 tcp:9757
adb shell am start -a android.intent.action.VIEW -d "wivrn+tcp://127.0.0.1:9757" org.meumeu.wivrn.github

If multiple devices are connected, add -s <serial> to each ADB command. Disable headset Wi-Fi while validating USB so the test cannot silently use wireless streaming. Recreate the reverse mapping after disconnecting USB.

Encoding and hardware validation

The package enables Vulkan Video encoding but does not enable NVENC. WiVRn 26.9 probes Vulkan encoding before falling back to VAAPI or x264 when NVENC is absent. Check the journal's encoder configuration after connecting: GPU activity alone does not prove hardware encoding. Vulkan encoding in this release supports H.264/H.265, not AV1. NVENC/AV1 requires a CUDA-enabled WiVRn build.

• Pair, connect, launch a game, and check both compositor and game GPU usage: nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv has to list both wivrn-server and the game.
• Confirm the journal has no vkAllocateMemory or xrt_comp_create_swapchain failures, and that ~/.local/state/xrizer/xrizer.txt has no ERROR_RUNTIME_UNAVAILABLE.
• Restart with systemd and verify the server remains owned by wivrn.service.
• Reboot the PC and reconnect without pairing again; verify saved settings and USB authorization remain intact.
• Test audio routing (just vr and just vr-stop), microphone, controllers, and a supported OpenXR/OpenVR game.

Configuration and package checks do not replace these headset tests.