Breezy Desktop: turning XR glasses into a second Linux display

What the project adds to a Linux desktop

Breezy Desktop is described as XR productivity and gaming applications for Linux, and more precisely as a collection of tools to enable virtual desktop environments for gaming and productivity on Linux using supported XR glasses.

The mechanism is display based rather than application based. The glasses appear to the desktop as a virtual monitor, so your existing windows can be placed on them, and multiple virtual monitors can exist alongside your physical ones. That is the whole idea, and it is why the tools are split by desktop environment and by graphics API rather than by application.

The hardware target is a specific list, maintained in the XRLinuxDriver repository, and the README insists twice that your glasses must be on that supported devices list and on the latest firmware.

The audience is Linux users with XR glasses who want them to work as a productivity display, and Linux gamers who want the glasses to work with Vulkan titles. The implementation is primarily JavaScript, the licence is GPL-3.0, the default branch is main, and the last push was on 2026-09-28 with releases v2.12.2 from 2026-09-15, v2.12.1 from 2026-09-10 and v2.12.0 from 2026-09-09.

The repository layout matches the two halves of the project. There are kwin/ and gnome/ directories for the desktop environment plugins, a vulkan/ directory for the gaming path, plus modules/, ui/, bin/, assets/ and a VERSION file at the root.

Two installations, and the warning to read first

There are two installation routes, and the README puts a warning above both of them.

The first is Breezy Desktop, for KDE Plasma or GNOME desktop environments on Linux. The second is Breezy Vulkan, described as primarily for gaming but which would work with pretty much any application that uses Vulkan rendering. That is a useful distinction: the desktop plugin is the route for extending your workspace, and the Vulkan path is the route for putting a game on the glasses.

The warning is about installing both, and it is specific. Do not manually install either of these if you are running the Decky plugin on the same machine, as they invalidate each other's installations, and the README notes that this is only temporary.

That is a signal about the state of the project. The Decky plugin is the Steam Deck route into XR on Linux, and the two approaches overlap enough that installing one breaks the other. A reader who already has the Decky plugin working should check with the project before touching the manual installers, because the two are currently mutually exclusive on the same machine.

There is also a pointer to a related project. The tip at the top of the README says that if you are interested in an XR desktop for Windows, macOS or Android, you can follow the work-in-progress Breezy Box project, with a demo video linked. So the Linux repository is the shipped piece, and the other platforms are still in progress.

The KDE Plasma setup and the X11 trap

Breezy Desktop is only compatible with KDE Plasma 6, and the KDE path installs a KWin script.

The bash route is four commands. You download the Breezy KWin setup script from the latest release, set the execute flag, and run it:

chmod +x ~/Downloads/breezy_kwin_setup

~/Downloads/breezy_kwin_setup

The script must be run with the glasses unplugged. After that you log out and back in, then enable the effect by opening the KDE Plasma System Settings app, going to the Desktop Effects tab, finding Breezy Desktop and enabling it.

The important branch in the instructions is the display server. If you see the warning Windowing system is X11 and you want to use virtual displays, the README splits the answer by platform. On SteamOS you use the Enable Breezy Wayland desktop script, and it warns that this will prevent you from accessing Game Mode again until you undo it by running the Disable Breezy Wayland desktop script. On other distributions you may be able to switch to Wayland from the login screen.

The reason is stated elsewhere in the README: if you are running KDE on X11, you will not be able to launch virtual displays, and if you are not on SteamOS you should look for Wayland options on the login screen. Steam Deck users are told there is an extra step in the setup instructions for switching to Wayland if they want the virtual display features.

So the ordering matters. Decide the session type before you run the setup, because the SteamOS route trades Game Mode access for virtual displays.

The Arch path and the xr-driver service

For non-SteamOS Arch users there is an AUR package, and the sequence differs from the script route in one important way: it enables a user service.

If you previously installed Breezy KWin with the setup script, you must uninstall it first, and the command given is breezy_kwin_uninstall. The README is explicit that the two methods invalidate each other.

The install and enable steps are:

yay -S breezy-desktop-kwin-git

systemctl --user enable --now xr-driver.service

Then you log out and back in, and enable Breezy Desktop from the KDE Plasma System Settings, the Desktop Effects tab.

The systemctl line is the piece that is easy to miss and important to understand. The virtual display support comes from a driver that runs as a user service, which is why the README tells you to enable it explicitly rather than letting the package do it.

The GNOME AUR route mirrors this exactly, with different package and script names. You uninstall a previous install with breezy_gnome_uninstall, then:

yay -S breezy-desktop-gnome-git

followed by the same systemctl --user enable --now xr-driver.service, and then a log out and back in.

For GNOME the bash route is the same shape as the KDE one, using the breezy_gnome_setup script with the execute flag set and the glasses unplugged, then a log out and back in.

The hardware caveats that decide whether this works

More of the README is caveats than instructions, and reading them is how you avoid a wasted afternoon.

The first is the glasses' own features. If you are using XREAL Ones, or other glasses that provide built-in 3DoF, stabilisation or anchoring features such as the VITURE Beast, you must disable all of those first using the menu on the glasses. Both the KDE and the GNOME sections repeat this instruction, which suggests it is the most common source of trouble.

The second is the desktop session. Virtual displays need Wayland, and both the KDE and GNOME paths say so in nearly the same words: if you are running KDE on X11 or GNOME on Xorg you will not be able to launch virtual displays unless you switch to Wayland.

The third is how the glasses behave on first connect. On KDE you are presented with options about how to extend your desktop that the README admits are not very clear, and it tells you to choose the No action option to leave the glasses' display independent. On GNOME, the equivalent is to open the Displays settings dialog and choose the Join option for multiple displays, so that the glasses extend your workspace rather than just mirroring your primary monitor.

The fourth is display configuration. On KDE, setting Visibility to always-visible in the Panel Settings prevents a broken taskbar, and disabling the Shake Cursor effect in System Settings under Accessibility prevents a magnified cursor appearing in the wrong place. On SteamOS you use the bash setup instructions, and on an immutable distro other than SteamOS you need the Distrobox setup from the project wiki.

One last practical note: for the best performance the README asks you to install the latest graphics drivers for your distribution, and after setup the Breezy Desktop application does not have to be running for the virtual desktop or the keyboard shortcuts to work, once you have configured them.

Licence, releases and what the project does not cover

The licence is GPL-3.0, with the LICENSE file at the repository root, which means anything you build on this code inherits copyleft obligations if you distribute it. The implementation is primarily JavaScript, and the repository is not archived, with the last push on 2026-09-28 and three releases in the space of a week in September 2026.

The scope limits are the more interesting part of an evaluation. Breezy Desktop is Linux only, and the README points at Breezy Box for Windows, macOS and Android as a work in progress. The desktop plugin supports KDE Plasma 6 and GNOME 45 through 51, which is a version range rather than an open-ended promise, and the KDE plugin is Plasma 6 only.

The user model is also narrower than the word desktop suggests. You get virtual monitors, and that is the mechanism. The glasses' own 3DoF, stabilisation and anchoring have to be switched off, so the spatial features that would justify an XR application are precisely the ones that conflict with this approach. It is a display solution, and the README is honest that it is one.

The other limit is the overlap with the Decky plugin, which the README calls temporary. If the two approaches are reconciled later, the instructions in this repository will change, and the version numbers here move quickly enough that you should read the README for the current version rather than trusting a cached copy of it.

For anyone planning to build on this, the sensible first step is to identify the desktop environment and session type you actually run, confirm the glasses appear in the supported devices list, and check whether the Decky plugin is already installed on that machine.

Editorial conclusion

Adopt Breezy Desktop if you are on Linux with supported XR glasses and want them to extend your workspace for productivity or for Vulkan games, and if your session is already Wayland. Do not adopt it if your glasses provide built-in 3DoF, stabilisation or anchoring, because the README requires you to disable all of those first, and skip it if you are on X11 with no route to Wayland, since virtual displays will not launch. Before you start, confirm your model is on the supported devices list, update the glasses firmware, and pick one install path, since the README warns that Breezy Desktop and the Decky plugin invalidate each other's installations.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. wheaney/breezy-desktop on GitHub