RiftLinux 0.1.3

RiftLinux is a modified Monado, specialized for full Oculus Rift CV1 support: the headset, its Constellation sensors
and its Touch controllers on Linux, in SteamVR and in OpenXR applications, from one package. No Windows, no Oculus
software, no Meta account.

This release makes games started from Steam go into the headset: Steam now starts SteamVR when you put the Rift on or
pick it up, as the Oculus app does on Windows. It adds settings for headsets whose wear sensor does not see the face
(face shields, thick pads), checks for what kept games from the headset on other setups, keeps SteamVR's and Steam's
menus out of the way, lets the Touch controllers sleep while the headset is not in use, and makes SteamVR more stable
when its parts stop or hang. It also has the fixes of the 0.1.2 pre-release (the GNOME desktop session ending, below).
Reports are very welcome.

New

• A headset taken off shows black instead of switching its display off. The display stays connected and shows
  pure black while the headset is not worn, and comes back at once when you put it on; after ten minutes black it
  switches off. Switched off, the CV1 leaves HDMI, and the desktop rebuilt its monitors at every take-off and put-on:
  GNOME 48 on NVIDIA kept GPU memory each time, until GNOME Shell ran out of memory after many.
  riftlinux-setup not-worn black <minutes> changes the time, not-worn off switches the display off as before.
• SteamVR starts when you put the headset on or pick it up. With Steam running, put the Rift on (or pick it up)
  and SteamVR starts by itself, the same way as a click on it in your library; a game you then start from Steam goes
  into the headset. Proton games (VRChat and most others) need SteamVR running before they start: started without it,
  they open on the monitor. Picked up only to be put away, the headset starts SteamVR too; it quits again by itself
  when the headset is not put on within two minutes and no game starts. riftlinux-setup autostart trigger put-on
  has only putting it on start SteamVR, autostart quit-unused off lets a SteamVR a pick-up started run on, and
  riftlinux-setup autostart off turns it off, for example if you use RiftLinux's own runtime without SteamVR.
• Settings for the wear sensor. A face shield, a thicker face pad or a covered sensor window can keep the sensor
  between the lenses from seeing your face, and the picture went dark while you wore the headset. riftlinux-setup wear-sensor test shows what it reads; wear-sensor levels sets its levels to fit your headset, wear-sensor off
  counts the headset as worn whenever SteamVR runs, and display-off sets how long after the headset is taken off its
  display switches off. All are in RiftLinux's settings file; the user guide's new
  Settings page explains them.
• riftlinux-setup check finds more of what keeps games from the headset: another headset driver registered with
  SteamVR or a driver forced in its settings (SteamVR-OpenHMD, ALVR), an OpenVR runtime other than SteamVR (xrizer,
  OpenComposite), SteamVR settings games depend on changed from their defaults, the lsusb command missing (Steam
  uses it to see that the headset is connected; the packages now depend on it), USB power saving on the Rift's
  devices, a desktop session holding thousands of leaked GPU handles (seen with GNOME on NVIDIA after screen
  recordings: programs started from it inherit them, and SteamVR Home could not open its files), and Steam still
  running the part of an older version that starts SteamVR (restart Steam), other VR services (Monado, WiVRn, ouvrt)
  or a camera app still holding the Rift's devices, a headset left in pairing mode, and variables or games' launch
  options that point games at another runtime (XR_RUNTIME_JSON, VR_OVERRIDE).
• riftlinux-setup fix puts the configuration RiftLinux is tested with in place, in one go: SteamVR as the OpenXR
  and OpenVR runtime, this driver as SteamVR's only headset driver (SteamVR-OpenHMD, ALVR or a copy in SteamVR's own
  drivers folder switched off; their files stay), SteamVR's settings games need, direct mode on, the devices' rules
  and USB power, and what other setups leave behind. It lists every change and asks once, and keeps every file it
  changes as a .bak-riftlinux-<time> copy.

Fixed

• SteamVR's standby ends only when you put the headset on. SteamVR also left its standby whenever the headset
  moved, by its own rule: a headset picked up, or lying on a bed someone moved on, woke it with nobody wearing it. It
  now follows the wear sensor. riftlinux-setup standby pick-up keeps SteamVR's own rule, as on Windows, where a
  headset picked up wakes SteamVR; the picture still waits until the headset is on.
• A headset held in the hands, or lying on a bed someone moves on, no longer shows the picture. A headset that
  moves as on a head counts as worn, for face shields and pads the wear sensor cannot see through. Held in the hands
  it moved alike and counted after a few seconds, and on a bed it did too. It now counts only after 20 seconds of
  moving and turning as a head does, and a headset lying on a bed shakes but does not turn. riftlinux-setup wear-sensor motion high|medium|low has it count sooner or later (8, 20 or 30 seconds), motion off counts the
  wear sensor alone.
• A settings file broken by an edit by hand no longer loses your settings. RiftLinux leaves the file as it is, uses
  the last settings it could read and writes nothing into it, where the commands and the Rift tab used to write a new
  file with only their own setting. riftlinux-setup check shows where it is broken, and which values in a file it
  can read are wrong; riftlinux-setup fix last-known puts the last good settings back (the broken file is kept).
• GNOME: the desktop session no longer ends when the headset's display goes dark (in the 0.1.2 pre-release). When
  the headset left HDMI, RiftLinux asked GNOME for the headset again and again, many times a second, until gnome-shell
  crashed and the session ended. Now it asks once the headset is back on HDMI, waits between tries when one fails, and
  hands the headset back to GNOME in the order GNOME expects.
• riftlinux-setup install --openxr steamvr stopped with a permission error when the OpenXR runtime set before
  was another runtime's file in /usr/share/openxr (in the 0.1.2 pre-release). It now switches to SteamVR.
• Games added to Steam as a Windows program start from SteamVR Home's library (a game installed outside Steam
  and added with "Add a Non-Steam Game", run with Proton, such as Beat Saber from another store). SteamVR ran the
  program itself, it ended at once, and SteamVR Home was left waiting; RiftLinux now has Steam start them, as Play in
  Steam's own library does.
• SteamVR is started again when its compositor stops. A compositor that stops showing frames (its graphics device
  lost, seen with NVIDIA as SteamVR left its standby or a game quit) left the headset frozen until SteamVR was closed
  by hand. The driver now closes SteamVR when its compositor shows nothing outside standby, and with Steam running
  SteamVR starts again by itself (once in ten minutes).
• SteamVR's shutdown no longer hangs. SteamVR could wait for good, as it quit, for a process that had already
  ended (its monitor after its compositor crashed on the way out, Steam's web helper after it aborted at a game's
  exit), and no SteamVR started again until it was ended by hand. The driver ends such a shutdown after 30 seconds,
  the headset's display dark first, together with SteamVR's monitor so that Steam sees SteamVR closed.
• The headset's display is switched off when nothing runs it. A SteamVR that crashed or was ended by hand left
  the display lit; the part in Steam that starts SteamVR now switches it off.
• SteamVR's compositor no longer waits for the driver every frame. The driver took each frame from SteamVR and
  waited for the headset's next refresh in the same call, so SteamVR's compositor waited too and logged a timeout for
  most frames; frames are now handed over after SteamVR's own work.
• SteamVR's menu no longer opens behind you at the start. SteamVR opens its menu as it starts, before RiftLinux
  places the room around you, and placing the room turned the menu away: it stood behind you, its back to you. It now
  shows once the room is placed, in front of you.
• The Touch controllers sleep while the headset is not in use. RiftLinux kept them awake for as long as SteamVR
  ran, also with the headset lying on the desk for hours, and their batteries ran empty. They now stay awake while you
  wear the headset and five minutes after; then a button wakes them. riftlinux-setup controller-sleep 3|5|7|off
  changes the minutes.
• A worn thumbstick that stops short of its range counts as fully pushed: a left stick pushed right reached only
  0.82-0.95 of its range, and a game's snap turn missed some pushes.
• Steam's menu closes once a game shows. Steam opens its menu as a game starts, and it stayed in front of the game.
  A menu you open with the menu button while the game runs stays; riftlinux-setup game-menu keep keeps Steam's.
• Your own sound output and microphone come back after a session that crashed. While the headset's headphones
  and microphone are the defaults, RiftLinux now notes yours; a session that ended without putting them back left
  the headset's as the defaults for good, and the next session puts yours back as it ends.
• USB power saving is off for the Rift's devices, also after the kernel's camera driver takes the sensors back:
  it turned it on again for them.
• SteamVR started by the headset no longer inherits the desktop's leaked handles, so SteamVR Home opens even
  then.
• Programs SteamVR starts (SteamVR Home, games) no longer get a copy of the driver's handles to the headset: one left
  running after SteamVR quit kept the headset open.
• The headset's wear input and its direct-mode settings were given to SteamVR only for headsets whose serial number
  was read; now for every CV1.
• Putting the headset on is seen at the wear sensor's levels you set (riftlinux-setup wear-sensor levels) for
  starting SteamVR too.

Tested on

• Ubuntu 25.04 (GNOME 48, Wayland) with NVIDIA 580: SteamVR started by picking the headset up and by putting it on
  (with only putting it on set), with Steam started from the desktop; VRChat and VTOL VR started from Steam then ran in
  the headset. SteamVR's menu showed in front once the headset was on, and Steam's menu closed as VTOL VR showed.
  A left Touch's stick turned in SteamVR Home on ten of ten pushes each way. With the headset put down, both
  controllers dropped to standby; picked up and put down again without wearing it, SteamVR quit by itself. A VR game
  started while SteamVR was not running opened on the monitor (Steam does not start SteamVR for it on Linux).
• Ubuntu 25.04 (GNOME 48, Wayland) with NVIDIA 580, unattended: SteamVR started and quit ten times with the headset
  counted as put on and taken off every minute (a test switch), with SteamVR Home, Beat Saber started from SteamVR
  Home's library (added to Steam as a Windows program) and VTOL VR in every session: every game started, no graphics
  errors, every quit clean. SteamVR's compositor stopped on purpose: SteamVR closed and started again by itself.
  RiftLinux's own runtime: the headset black while not worn, switched off after the black time and back when put on.
• Ubuntu 25.04 (GNOME 48, Wayland) with NVIDIA 580: SteamVR's standby with each of its two settings, with the
  head-movement rule on and off: moving on the bed with the headset lying on it, holding the headset and looking into
  it, putting it down and putting it on; in each of the four, the headset woke and showed its picture as set.
• The GNOME fix, with the 0.1.2 pre-release: Ubuntu 26.04 (GNOME 50.1, Wayland) with an AMD Radeon RX 9070 XT
  (Mesa 26.0.8), from a live USB stick, the headset taken off and put on again with SteamVR running: GNOME offered the
  headset while it was off HDMI, RiftLinux waited, the picture came back when it was worn, and the desktop kept
  running; CachyOS (KDE Plasma, Wayland) with NVIDIA 615, the headset's HDMI unplugged and plugged back: the picture
  came back as it was plugged in.
• The packages are installed and checked in clean Ubuntu 22.04, 24.04 and 26.04, Debian 12 and 13, Fedora 43 and 44,
  and Arch systems.
• Not tested here: AMD and Intel graphics for this release's other changes.
• x86-64 computers only.

Install

Download the package for your distribution and SHA256SUMS below, check them with
sha256sum --ignore-missing -c SHA256SUMS, and install (an upgrade from an earlier version is the same command):

sudo apt install ./riftlinux_0.1.3_amd64.deb                  # Debian, Ubuntu, Linux Mint, Pop!_OS
sudo pacman -U riftlinux-0.1.3-1-x86_64.pkg.tar.zst           # Arch, CachyOS, EndeavourOS, Manjaro
sudo dnf install ./riftlinux-0.1.3-1.x86_64.rpm               # Fedora
tar xf riftlinux-0.1.3-x86_64.tar.gz && sudo ./riftlinux-0.1.3-x86_64/install.sh   # any other distribution

Then restart Steam once (Steam, Exit, and start it again): it loads the part that starts SteamVR as it starts, and an
update's version only after a restart. Plug in the Rift and put the headset on: SteamVR starts. The
user guide walks through the first start; the README has
the settings and the comparison with other options.

Known issues

• A VR game started from Steam while SteamVR is not running opens on the monitor: Steam on Linux does not start
  SteamVR for it. Put the headset on first (SteamVR then starts), or start SteamVR from Steam, then the game.
• Steam's client can crash when a flat (non-VR) game opens a window while SteamVR runs: a Valve bug, not this driver
  (SteamVR for Linux #963: the same crash, reported for the Desktop tab).
• SteamVR's compositor can crash as SteamVR quits, after the session has ended: harmless, and SteamVR's own exit code
  (SteamVR for Linux #990: the same crash with Valve's own streaming driver).
• SteamVR's compositor sometimes does not start at the first try (2 of 30 test starts; a freeze in SteamVR's own
  start): SteamVR tries again and SteamVR Home appears later than usual. RiftLinux ends the copy of SteamVR's server
  the failed try leaves behind once SteamVR quits, so the next start is not blocked.
• Steam asks some questions before a game's first start on the monitor, not in the headset: if a game does not
  start from inside VR, take the headset off and answer them there.
• SteamVR's Desktop tab is empty on Linux (SteamVR for Linux #693); WayVR shows the desktop as an overlay.
• With NVIDIA on Wayland and a VRR monitor, the headset's picture can tear unless VRR is hidden from the driver
  (NVIDIA's bug, open-gpu-kernel-modules #992): riftlinux-setup nvidia-vrr conceal.
• GNOME with HDR on can leave the desktop's colours washed out when the headset connects or disconnects; switching
  HDR off and on in GNOME's settings restores them (likely mutter #5083, fixed for GNOME 51).

The README's Known issues section has the full list, including app issues under Proton.

Reporting a problem

Open an issue with the bug form and add the output of riftlinux-setup --json check, SteamVR's log
(~/.local/share/Steam/logs/vrserver.txt) and the driver's own log (~/.steam/steam/logs/vrstartup-linux.txt);
say which GPU and driver you have.

For a tracking problem, record a session: run riftlinux-setup record on, start SteamVR and do what shows the
problem, then attach the recording from ~/.cache/riftlinux and SteamVR's startup log
(~/.steam/steam/logs/vrstartup-linux.txt). Turn it off afterwards with riftlinux-setup record off.