# WayVR for Linux VR desktops and in-headset apps

> WayVR is a Rust-based OpenXR and OpenVR overlay that brings Wayland and X11 screens into supported Linux VR runtimes and can launch apps in virtual space. It is most relevant to Monado, WiVRn, and SteamVR users who want desktop access without changing their VR runtime.

**wayvr-org/wayvr** — Your way to enjoy VR on Linux. Run apps inside VR & access your Wayland/X11 screens from Monado/WiVRn/SteamVR.

- Repository: https://github.com/wayvr-org/wayvr
- Website: https://wayvr.org
- Stars: 1,458 · Forks: 145
- Language: Rust
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/wayvr-org-wayvr

## WayVR's Linux VR desktop role

WayVR addresses a specific gap between a normal Linux desktop and a VR session. A headset user can access Wayland or X11 screens while remaining in VR, mirror selected content into the headset, and launch applications directly into a three-dimensional environment. The intended audience is therefore broader than VR application developers. It is aimed at Linux users who already run Monado, WiVRn, SteamVR, or one of the supported configurations mentioned in the project documentation and need a desktop layer inside the headset.

The project describes itself as an OpenXR and OpenVR overlay rather than as a full VR compositor or standalone headset runtime. That boundary matters. WayVR is intended to run alongside an existing VR session, which means the runtime starts first and WayVR becomes an overlay or plugin in that environment. Its goal is low-impact rendering, but the README gives no benchmark figures or measured frame-time results. Any evaluation of its performance must therefore account for the selected runtime, VR application, display server, and hardware rather than treating the project's positioning as a measured guarantee.

WayVR also provides a watch-based control surface, selected overlays, and a working set that can be hidden, shown, and recentered. This is more than a one-screen mirroring utility: screens, mirrors, the keyboard, and other overlays can participate in a spatial workspace. However, the README describes the interaction model more clearly than it describes persistence, packaging internals, or upgrade compatibility. Those details should not be inferred from the presence of a configurable UI.

## WayVR overlay architecture and screen data flow

Based on the repository layout, WayVR is implemented primarily in Rust as a Cargo workspace. The `wayvr` crate sits alongside `wayvr-ipc`, `wayvrctl`, rendering and interface crates such as `wgui` and `uidev`, and screen-capture components named `wlx-capture` and `wlx-common`. Separate desktop and capture crates indicate that the overlay, control interface, IPC, command-line support, and Wayland capture duties are not confined to one executable module.

The documented screen-selection flow begins after WayVR starts and the runtime presents a screen-share request. The user selects screens in the requested order, using notifications or terminal prompts if the desktop notification is not visible. WayVR then treats those selections as part of its working set, the collection of overlays currently placed in front of the headset. The `Clear PipeWire tokens` control followed by `Restart software` resets the selection process when displays were assigned in the wrong order.

Input is organized around colored pointer modes. Under the default settings, a blue laser produces left clicks, orange produces right clicks, and purple produces middle clicks. Moving an overlay requires grabbing it and using the joystick. Resizing uses grab, click, and joystick together. Edit mode permits repositioning and changing overlay behavior, including moving the watch between hands. These details show that WayVR translates both desktop capture and VR controller input into an editable spatial workspace.

## AppImage installation and first VR session

The quickest documented distribution option is the latest AppImage from the GitHub Releases page. For SteamVR through Steam Flatpak, the README requires extracting the AppImage because the resulting application directory must be accessible to the Flatpak sandbox. Replace `/path/to/squashfs-root/AppRun` with the actual location after moving the extracted directory.

Extract the downloaded AppImage and make its entry point executable:

```bash
WayVR-*.AppImage --appimage-extract
chmod +x squashfs-root/AppRun
```

The extraction creates `squashfs-root`. The README then calls for moving that directory to a location Steam Flatpak can access and granting access to the PipeWire runtime socket:

```bash
flatpak override com.valvesoftware.Steam --user --filesystem=xdg-run/pipewire-0/:rw
```

Restart Steam, start SteamVR, then invoke the extracted application through Steam's Flatpak command:

```bash
flatpak run --command='/path/to/squashfs-root/AppRun' com.valvesoftware.Steam
```

WayVR does not register itself for SteamVR auto-start, so the user must launch it manually after SteamVR is running. When the screen-share prompt appears, select the displays in the exact requested order. The resulting home environment uses headset passthrough by default or a configured background.

For Monado or WiVRn, the README says no additional Flatpak Steam compatibility setup is required. Start the VR runtime, run WayVR, and select WayVR in WiVRn's `Application` drop-down. If that entry is absent, select `Custom` and browse to the executable or AppImage. These are different integration paths, so copying the Steam Flatpak permission command to a Monado or WiVRn setup would go beyond the documented procedure.

## Editing WayVR overlays and correcting display order

The first usable WayVR workspace is controlled primarily from the watch on the left wrist. The watch shows device batteries at the top and overlay controls at the bottom. The main working set can be revealed with a double tap of B or Y on a non-Vive controller. Vive users double-tap the menu button on the left controller, although SteamVR requires the `showhide` binding to be assigned.

Edit mode is available from the watch, the keyboard taskbar's hamburger menu, or the title bar of a WayVR app. In this mode, the user can grab and reposition overlays and access per-overlay options. The watch itself can also be moved and passed between hands. After it is grabbed, it attaches to the hand opposite the one that held it.

Screen selection has one explicit recovery path. If two displays were chosen in the wrong order, open Settings, press `Clear PipeWire tokens`, then use `Restart software`. Notifications explain the next selection sequence. If notifications are absent, the README says to start WayVR from a terminal and follow its printed instructions. This procedure addresses ordering, but the README does not document a separate recovery process for a failed extraction, incompatible runtime, or broken Flatpak permission. Such failures are outside the confirmed setup guidance.

## WayVR limitations and runtime-specific boundaries

SteamVR is the clearest limitation because WayVR no longer registers for auto-start due to bugs in SteamVR. Manual launch is part of the current documented workflow, not an optional convenience. The Steam Flatpak path also requires filesystem access to the extracted AppImage and a PipeWire socket override, so a host-level installation may not be enough for that configuration.

Steam Frame support is explicitly experimental. The README says WayVR can run there in headless mode and place applications in 3D space, but it cannot provide access to a KDE desktop. It recommends High overlay quality in the Frame's SteamVR settings, yet it also asks users to report issues. This is a limited deployment target rather than equivalent support for a desktop Linux installation.

WayVR is also the wrong tool when the requirement is a complete Linux VR shell without an existing supported runtime. The project expects Monado, WiVRn, or SteamVR to be started first. Users who want Envision should use its plugin route: enable WayVR in the Plugins menu. If WayVR is missing, installation must expose it in the desktop application menu; GearLever can install a downloaded AppImage and create that entry.

The repository does not identify a named alternative overlay in the README, so a feature-by-feature competitor comparison would be unsupported. The clearest integration alternative shown is Envision's plugin mechanism, which loads WayVR as a plugin. That differs in activation and ownership of the entry point, but it still uses WayVR rather than replacing its capture and overlay implementation. This limitation in available comparison data is worth noting before selecting a different project for a different architecture.

## WayVR releases, Rust workspace, and GPL-3.0 upkeep

The repository is not archived, and its last push was on 2026-10-17. Recent tagged releases include v26.8.0 on 2026-08-09, v26.7.1 on 2026-07-14, and v26.7.0 on 2026-07-06. These dates show recent repository activity and release output, but they do not by themselves describe the compatibility policy between versions.

The Cargo workspace uses resolver version 3 and groups application, IPC, command-line, interface, and capture crates. Its release-related profiles include `release-with-debug`, while `plain` inherits development optimization but strips debug information and removes debug symbols. The dependency list includes PipeWire, Wayland client and protocol crates, X11-adjacent windowing support through `winit`, serialization, IPC, and UI dependencies. Upgrade cost can therefore include source rebuilds when building from Rust rather than simply replacing an AppImage.

WayVR is licensed under GPL-3.0. That identifier defines the repository's stated license terms, including the source and distribution obligations associated with the GPL. This review does not provide legal advice or assess a particular distribution scenario. The README links to source-building documentation but does not reproduce its commands, dependency prerequisites, or upgrade procedure. Users who need repeatable local builds should consult that linked guide rather than assuming that an AppImage update is equivalent to a source workspace migration.

## Conclusion

WayVR is a practical choice for Linux VR users who need desktop screens, mirrors, a keyboard, or applications inside the headset. It is a poorer fit for people who expect SteamVR auto-start, KDE desktop access on Steam Frame, or documented rollback procedures. Verify first that your VR runtime, display server, Flatpak boundary, and screen-selection order work with the installed package.

## FAQ

### How do I install WayVR on Linux?

The README lists AppImage, AUR, Nix, Homebrew-XR, and source-building routes. The SteamVR through Steam Flatpak setup specifically requires extracting the AppImage, granting access to `xdg-run/pipewire-0/:rw`, and launching `squashfs-root/AppRun` through Steam Flatpak.

### Which VR runtimes can WayVR connect to?

The documented runtimes are Monado, WiVRn, and SteamVR. The runtime must be started before WayVR, although Envision users can instead enable WayVR from its Plugins menu.

### Why is my WayVR screen in the wrong order?

Open Settings, select `Clear PipeWire tokens`, and restart the software. Then follow the requested screen-selection order using notifications or the instructions printed in a terminal.

### Does WayVR start automatically with SteamVR?

No. The README says WayVR no longer registers for SteamVR auto-start because of SteamVR bugs, so SteamVR users must start it manually.

### Can WayVR provide a KDE desktop on Steam Frame?

No. Steam Frame support is experimental and runs in headless mode, allowing applications in 3D space but providing no access to the KDE desktop.

## Sources

- [License: GPL-3.0](https://github.com/wayvr-org/wayvr/blob/main/LICENSE)
- [Project website](https://wayvr.org)
- [README](https://github.com/wayvr-org/wayvr/blob/main/README.md)
- [Releases](https://github.com/wayvr-org/wayvr/releases)
- [wayvr-org/wayvr on GitHub](https://github.com/wayvr-org/wayvr)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wayvr-org-wayvr