wayvr

WayVR (previously WlxOverlay-S)

A lightweight OpenXR/OpenVR overlay for Wayland and X11 desktops.

WayVR lets you access your desktop screens while in VR, and even launch apps directly in VR.

In comparison to similar overlays, WayVR aims to run alongside VR games and experiences while having as little performance impact as possible. The UI appearance and rendering techniques are kept as simple and efficient as possible, while still allowing a high degree of customizability.

Join the Linux VR Community

We are available on either Discord or Matrix space:

Questions/issues specific to WayVR will be handled in the wayvr chat room. Feel free to ask anything.

Setup

Installation

There are multiple ways to install WayVR:

1. AppImage: Download from Releases
2. AUR package: wayvr or wayvr-git
3. Nix package: wayvr or unstable package from nixpkgs-xr
4. Homebrew-XR package (for Bazzite, etc.): wayvr
5. Docs: Building from source.

General Setup

1. Start Monado, WiVRn or SteamVR.
2. Run the overlay

Note: If you are using Monado or WiVRn, no additional setup steps are required for Flatpak Steam compatibility—most people use WayVR seamlessly with Monado/WiVRn.

SteamVR via Steam Flatpak

For users specifically running SteamVR via Steam Flatpak, follow these steps:

1. Grab the latest AppImage from Releases.
2. WayVR-*.AppImage --appimage-extract
3. chmod +x squashfs-root/AppRun
4. Move the newly created squashfs-root folder to a location accessible by the Steam Flatpak.
5. flatpak override com.valvesoftware.Steam --user --filesystem=xdg-run/pipewire-0/:rw
6. Restart Steam.
7. Start SteamVR.
8. flatpak run --command='/path/to/squashfs-root/AppRun' com.valvesoftware.Steam

First Start

When the screen share pop-up appears, check your notifications or the terminal and select the screens in the order it requests.

In case screens were selected in the wrong order:

• Go to Settings and press Clear PipeWire tokens and then Restart software
• Pay attention to your notifications, which tell you in which order to pick the screens.
• If notifications don't show, try starting WayVR from the terminal and look for instructions in there.

WiVRn users: Select WayVR from the Application drop-down. If there's no such entry, select Custom and browse to your WayVR executable or AppImage.

Envision users: Go to the Plugins menu and toggle on the WayVR plugin. If WayVR isn't in the Plugins list, or the list is empty, ensure you've installed WayVR fully, such that it appears in your Desktop Environment's application menu. If you've downloaded the WayVR AppImage, Gear Lever can install it, which creates the application menu entry.

SteamVR users: WayVR no longer registers itself for auto-start, due to bugs in SteamVR. For now, you must start WayVR manually.

This will show a home environment with headset passthrough enabled by default or a customizable background!

Please continue reading the guide below.

Getting Started

Working Set

The working set consists of all currently selected overlays: screens, mirrors, keyboard, etc.

The working set appears in front of the headset when shown, and can be re-centered by hiding and showing again.

Show and hide the working set using:

• Non-vive controller: double-tap B or Y on the left controller.
• Vive controller: double-tap the menu button on the left controller (for SteamVR, the showhide binding must be bound)

Moving overlays: Grab + Joystick

Resizing overlays: Grab + Click + Joystick

Pointer Modes AKA Laser Colors

Much of the functionality in WayVR depends on what color of laser is used to interact with a UI element.
Using the default settings, there are 3 modes:

• Regular Mode: Blue laser
• Right-click Mode: Orange laser
• Middle-click Mode: Purple laser

Please see the bindings section below on how to activate these modes.

The guide here uses the colors for ease of getting started.

Edit mode

Ways to enter Edit mode:

• Edit mode button on Watch face
• Taskbar (top of keyboard) hamburger menu
• Edit mode button on the title bar of WayVR apps (next to X button)

Edit mode lets you grab overlays and reposition them in yourset.

It's also possible to change overlay behavior and tweak your overlays in different way.

While in edit mode, try hovering over various overlays to see their options!

The watch

Check your left wrist for the watch. The watch is the primary tool for controlling the app.

The top of the watch shows device batteries, and the bottom shows your overlay controls.

While in edit mode, the watch can also be grabbed and passed between your hands.

After grabbing, the watch will automatically attach to the hand that's opposite from the one that held it.

The screens

Hovering a pointer over a screen will move the mouse. If more than one pointer is hovering over a screen, the pointer that was last used to click will take precedence.

The click type depends on the laser color:

• Blue laser: Left click
• Orange laser: Right click
• Purple laser: Middle click
• Stick up/down: Scroll wheel

The keyboard

The keyboard sends keys to the screen or WayVR application with the most recent mouse interaction.

On top of the keyboard is the taskbar, which lists WayVR apps as well as screens, mirrors and panels overlays.

Typing

• Use the BLUE laser when typing regularly.
• While using the ORANGE laser, all keystrokes will have SHIFT applied.
• Purple laser is customizable via the settings, no modifier by default.

Modifier Keys are sticky. They will remain pressed until either:

• a non-modifier key is pressed
• the modifier is toggled off by clicking again
• the keyboard is hidden (including via show-hide)

Default Bindings

Changing Bindings

• SteamVR: Simply change the bindings from the SteamVR bindings section.
  • If WayVR doesn't show up on the list, select any other title and then press back on the top left. (SteamVR bug)
• Monado/WiVRn: See WayVR Dashboard → Settings → Controls.

Customization

See these relevant wiki pages:

• For all available config options, check Docs: Configuration
• Looking to customize look & feel, or add functionality? See Docs: Customization
• Looking to change the OpenXR background? See Docs: OpenXR Skybox

Troubleshooting

When an error is detected, we often print tips for fixing it into the log file.

Logs will be at /tmp/wayvr.log for most distros.

Check here for tips.

Known Issues

Mouse movement is wrong

If the mouse is moving on a completely different screen, the screens were likely selected in the wrong order:

• Go to Settings and press Clear PipeWire tokens and then Restart software
• Pay attention to your notifications, which tell you in which order to pick the screens.
• If notifications don't show, try starting WayVR from the terminal and look for instructions in there.

If the mouse is on the correct screen but moves in weird ways, enter Edit Mode, hover the screen and under Mouse Fixes, select the mode that works.

COSMIC desktop:

• Due to limitations with COSMIC, the mouse can only move on a single display.

X11 users:

• Might be dealing with a Phantom Monitor.
• DPI scaling is not supported and will mess with the mouse.
• Upright screens are not supported and will mess with the mouse.

Screens or launched apps don't work when auto-started by SteamVR or WiVRn

SteamVR starts WayVR in the Steam runtime, and systemd/flatpak WiVRn can also start WayVR in a sub-optimal environment.

The easiest fix is to start WayVR separately. It's possible to start WayVR before starting SteamVR/WiVRn by passing --wait:

• wayvr --wait or /path/to/WayVR.AppImage --wait

X11 limitations

• X11 capture can generally seem slow. This is because zero-copy GPU capture is not supported on the general X11 desktop. Consider trying Wayland.
• DPI scaling is not supported and may cause the mouse to not follow the laser properly.
• Upright screens are not supported and can cause the mouse to not follow the laser properly.
• Screen changes (connecting/disconnecting a display, resolution changes, etc) are not handled at runtime. Restart the overlay for these to take effect.