* fix(setup): verify provisioning and runtime readiness * feat: add explicit per-user uninstall and purge * fix: restore niri input and provide native capture and tray * fix(build): declare Wayland scanner and release dependencies
15 KiB
Platform support and usage
uur selects Linux integrations by observable capability. Distribution and
desktop names below help users install the right dependencies. uur doctor
reports the active login session.
The current release target is Linux x86_64. Wine must be able to run the official 64-bit UU Remote client.
Runtime dependency axes
| Capability | Preferred route | Alternatives |
|---|---|---|
| Wayland video | ScreenCast portal + PipeWire | Portal virtual/window sources |
| X11 video | Wine X11 capture | ScreenCast portal when explicitly selected |
| Wayland input | RemoteDesktop portal | uinput; XTest for XWayland windows |
| X11 input | XTest | uinput |
| Audio | PulseAudio protocol | pipewire-pulse; ALSA |
| Wine windows | X11/XWayland | Wine Wayland driver |
| Application launch | gio launch |
gtk-launch |
| Suspend inhibition | Inhibit portal | Session continues without an inhibitor |
| WOL persistence | NetworkManager + ethtool | ethtool runtime state |
| Hardware inventory | DRM + VA-API/Vulkan Video | NVENC/NVDEC; software codec |
Common portal packages include xdg-desktop-portal-gnome,
xdg-desktop-portal-kde, xdg-desktop-portal-hyprland,
xdg-desktop-portal-wlr, xdg-desktop-portal-lxqt,
xdg-desktop-portal-xapp, xdg-desktop-portal-gtk, and compositor-specific
implementations. The active interfaces determine the selected path.
Install by distribution family
Arch package family
This includes Arch Linux and distributions that consume Arch packages or the AUR, such as EndeavourOS, CachyOS, Manjaro, Garuda Linux, Artix Linux, and Arch-based development systems. Init-system choice does not affect uur; it does not require a persistent systemd service.
From AUR:
paru -S uur
From a downloaded Arch package:
sudo pacman -U ./uur-0.1.4-1-x86_64.pkg.tar.zst
Install the portal backend supplied or recommended by the selected desktop.
On a capture-only Wayland portal, ensure the active user can open
/dev/uinput; the package installs a udev rule and a module-load entry.
Debian package family
The deb artifact is intended for current Debian, Ubuntu, Linux Mint, Pop!_OS, Zorin OS, elementary OS, KDE neon, TUXEDO OS, Kali Linux, MX Linux, and other compatible derivatives:
sudo apt install ./uur_0.1.4_amd64.deb
The package manager resolves Wine, PipeWire, and the portal frontend. Install the session's portal backend separately when the distribution does not pull it in with the desktop environment.
RPM package family
The rpm artifact targets current Fedora and distributions with compatible RPM dependency names. Install it with the native frontend:
# Fedora and compatible systems
sudo dnf install ./uur-0.1.4-1.x86_64.rpm
# openSUSE family
sudo zypper install ./uur-0.1.4-1.x86_64.rpm
RHEL, CentOS Stream, Rocky Linux, AlmaLinux, Oracle Linux, Nobara, Ultramarine, openSUSE Tumbleweed, and openSUSE Leap can use the RPM when its dependency names resolve, with the portable or source build covering other package layouts.
Other conventional distributions
Gentoo, Funtoo, Void Linux, Slackware, Solus, Clear Linux, Mageia, OpenMandriva, PCLinuxOS, and similar mutable/FHS systems can use the portable archive when they provide compatible glibc, Wine, PipeWire, and portal libraries:
sudo tar --zstd -C / -xf ./uur-0.1.4-linux-x86_64.tar.zst
Alternatively, build and install for one user:
cargo build --release --locked
./hook/build.sh
./capture/build.sh
./scripts/install-user.sh
The source build needs Rust, a native C compiler, PipeWire development files,
pkg-config, and the MinGW-w64 x86_64 compiler and binutils. Package names are
distribution-specific; uur does not invoke a package manager itself.
Immutable, declarative, and musl systems
NixOS uses the repository flake and NixOS module described in Nix and
NixOS. The module installs the package, udev integration, and uinput
kernel module declaratively.
Alpine edge uses packaging/alpine/APKBUILD or the included musl container
build. GNU Guix can package the same staged layout. Flatpak and Snap require
host input, Wine, and portal permissions that are best expressed as dedicated
manifests.
Select the desktop integration path
X11 session
Requirements: DISPLAY, Wine's X11 driver, and the XTest extension.
This path applies to full desktops and standalone window managers alike. Common examples include Xorg sessions of GNOME, Plasma, Cinnamon, MATE, Xfce, LXQt, LXDE, Budgie, Deepin, Pantheon, Trinity, and UKUI, plus i3, bspwm, awesome, Openbox, Fluxbox, IceWM, dwm, qtile, herbstluftwm, spectrwm, and FVWM.
Wine captures the X11 desktop directly and uur injects input with XTest. A ScreenCast portal is not required for this path.
Wayland session with ScreenCast and RemoteDesktop portals
Requirements: a working session D-Bus, PipeWire, the xdg-desktop-portal
frontend, and a backend exposing both ScreenCast and RemoteDesktop.
Where those interfaces are available, uur creates one combined session for capture and input. This is the preferred unprivileged route. Examples can include current GNOME Shell, KDE Plasma, COSMIC, and other sessions whose selected portal backend advertises both interfaces. Interface availability—not the desktop name—makes the final decision.
Wayland session with a capture-only portal
Requirements: ScreenCast/PipeWire plus writable /dev/uinput for full desktop
input. XTest remains only a partial fallback for XWayland surfaces.
This route commonly applies to compositors using Hyprland or wlroots-oriented
portal backends, including Hyprland, Sway, Wayfire, river, labwc, dwl, Waybox,
and other wlroots-based sessions. niri uses its recommended
xdg-desktop-portal-gnome ScreenCast integration and requires uinput when a
working RemoteDesktop session is unavailable. It may also apply to a desktop whose portal
installation is incomplete or whose selected backend omits RemoteDesktop.
Install the compositor's ScreenCast portal and enable uinput access. A
portals.conf selects the backend when several are installed.
Wine window backend
The UU user interface still needs a Wine display driver:
- Existing X11 and most Wayland desktop sessions normally use Wine through X11 or XWayland.
- Compositors without built-in XWayland can use an external XWayland manager; niri, for example, integrates xwayland-satellite in current releases.
- Wine builds with a usable native Wayland driver may run without XWayland, but that combination must still pass UU WebView2 and window-management tests.
This choice is independent from desktop capture. A client window can use XWayland while the controlled desktop is captured through the Wayland portal.
Audio servers
Wine's PulseAudio driver is selected for both a native PulseAudio daemon and
the pipewire-pulse compatibility server. A native PipeWire session without
PulseAudio compatibility uses Wine's ALSA driver. uur doctor prints the live
choice; this is independent from PipeWire's Wayland video role.
Displays and virtual sources
uur display status
uur display source monitor
uur display source window
uur display source virtual
The command clears the old restore token so the next Portal session can create or select the requested source. X11 exposes its XRandR topology to Wine. Wayland currently carries one selected stream; independent multi-stream switching is the next display-topology adapter.
First run and normal use
After installing any package format:
uur doctor
uur setup --accept-eula
uur run
Optional host integration is managed explicitly:
uur autostart enable
uur autostart status
uur wol status
sudo uur wol enable --interface enp3s0
The WOL command configures the real Linux adapter; it requires ethtool, and
persists the setting through an active NetworkManager wired profile when one
exists. The adapter name above is only an example—omit it for automatic
physical-interface selection.
The package installs uur.desktop as the canonical application-menu entry.
During setup, an existing Wine-generated Linux desktop entry for the official
client is converted into a hidden compatibility alias whose command is also
uur run. This keeps already pinned Dock, panel, or launcher favorites working
without showing a duplicate application in new searches.
The .lnk file inside the Wine prefix remains available for diagnosis. Normal
desktop integration launches uur.desktop or uur run so all helpers share
the same lifetime.
The first Wayland run may show a portal chooser. Select the monitor to expose to remote controllers. A successful persistent portal grant is reused where the backend supports restore tokens.
UU Quick Launch is populated from visible XDG desktop entries every time
uur run starts. This includes conventional packages and any containerized or
portable application that publishes a valid .desktop entry. Application
activation uses the desktop entry itself, so uur does not maintain a command
translation table.
Stop only the managed session and its Wine prefix with:
uur stop
Useful input-backend overrides for diagnosis are:
UUR_INPUT_BACKEND=portal uur run
UUR_INPUT_BACKEND=uinput uur run
UUR_INPUT_BACKEND=xtest uur run
An override is a diagnostic tool, not a desktop-specific configuration. The
default auto mode should be used after troubleshooting.
Interrupted setup and Wine components
Retry an interrupted installation without deleting the managed prefix:
uur stop
uur setup --repair
uur doctor
uur run
The repair option runs wineboot --update for the managed prefix. This retries
Wine's component initialization, including its Wine Mono offer where needed.
It keeps the installed client's data, checks both the client and service
executables and the Windows service registration, and reruns the official
installer if that installation is incomplete. Failed initialization or a
failed/cancelled installer returns an error instead of reporting completion.
The Wine Mono Installer is Wine's .NET runtime installer. It is separate
from WebView2, which uur uses for the official client's management UI.
Cancelling Mono does not establish the cause of a Wayland black screen or
failed desktop input. Those paths depend on the native capture helper,
ScreenCast/PipeWire and an authorized RemoteDesktop session or uinput.
On Arch/CachyOS, installing the matching wine-mono package can avoid the
Wine dialog's network download; use the package supplied for the installed
Wine version. For the existing 0.1.4 release, the equivalent manual retry is:
uur stop
WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}/uur/wine" \
WINEDLLOVERRIDES="wevtapi=b,wtsapi32=b" wineboot --update
uur setup
To open the Wine program/component manager for this prefix:
WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}/uur/wine" \
WINEDLLOVERRIDES="wevtapi=b,wtsapi32=b" wine uninstaller
niri: black video or missing desktop input
Use the niri session entry (or niri-session), its recommended
xdg-desktop-portal-gnome backend, and a running PipeWire service. A visible
Wine window only verifies its XWayland display path. Remote video still needs
the separate ScreenCast stream, and native Wayland input needs a working
RemoteDesktop session or writable /dev/uinput.
Start with an actual monitor selection:
uur display source monitor
uur doctor
test -w /dev/uinput && echo 'uinput is writable'
uur run
If the portal chooser offers niri Dynamic Cast Target, that stream remains empty until a target is assigned through niri. Select a real monitor when diagnosing black video. See niri's screencasting documentation. If RemoteDesktop creation fails, the automatic policy tries uinput. When both are unavailable it reports an error; explicitly selected XTEST can only reach XWayland windows. The packaged udev rule and uinput module must be active for the logged-in user; restart the graphical session after changing that setup.
uur run verifies a real Wayland frame and a running GameViewerService before
announcing readiness. Startup/helper failures are reported in the terminal;
details are in ${XDG_STATE_HOME:-$HOME/.local/state}/uur/session.log and
${XDG_DATA_HOME:-$HOME/.local/share}/uur/hook.log. A missing tray icon alone
does not determine whether capture or input works.
For niri and other compositors exposing wlr-screencopy, uur also offers
direct, shared-memory monitor capture. This path avoids portal/PipeWire/GBM
dependencies for video and is useful when a portal cannot produce frames:
uur display outputs
uur display backend wayland --output DP-1 # Use the name printed above
uur run
Selecting wayland explicitly authorizes direct monitor capture for later
runs. It does not show a system screen-sharing dialog and does not activate
automatically after portal cancellation or failure. With one output, --output
can be omitted; multiple outputs require an explicit name. Automatic input
selection uses uinput in this mode. Run uur display backend portal to return
to portal-consented capture. Direct mode captures a monitor, not individual
windows or virtual portal sources; changes to its size require restarting
the session.
The supervised native StatusNotifierItem supplies its own icon pixels and DBusMenu to Noctalia, Plasma and other compatible panels. Right-click it for Open UU Remote and Quit. It re-registers when the panel's watcher restarts; it does not depend on Wine's legacy tray being visible.
Reading uur doctor
portal ScreenCast: required to capture a Wayland desktop.portal RemoteDesktop: preferred unprivileged Wayland input route.uinput (/dev/uinput): full-desktop fallback when RemoteDesktop is absent.DISPLAY: required for Wine/X11 or Wine/XWayland and for XTest fallback.WAYLAND_DISPLAY: identifies the active Wayland session.PipeWire: required for the Wayland frame transport.
If both Wayland input routes are unavailable, XTest controls XWayland windows.
Session model
Portal sessions operate in the logged-in desktop seat. Display-manager access
uses a display-manager remote session, while headless operation uses a portal
virtual source or a provisioned virtual display. uur doctor reports the
active backend capabilities.
Relevant upstream documentation: