Introduction
For years, Linux users on Wayland faced a difficult choice: stick with the legacy X11 display server just to use remote desktop tools, or sacrifice unattended access for the security of Wayland. Wayland's architecture makes screen capture and input injection privileged operations, requiring user consent for every session. That has made automation and remote support nearly impossible.
In 2026, RustDesk changed the game. The latest stable releases now offer true unattended remote access on Wayland. This means you can connect to a Wayland-based machine without anyone having to sit at the screen and click "Share" or "Allow." This guide walks you through exactly how it works, and how to set it up step by step.
Why Wayland Was the Last Frontier for Remote Desktop
To appreciate the significance, you need to understand the difference between X11 and Wayland. X11 is a display server protocol designed in the 1980s. It allows any application to read all keyboard input and capture the screen, which makes screen sharing trivial but also creates security vulnerabilities. Wayland was designed to fix these flaws by isolating clients. The compositor is the single authority for display and input, and any privilege like screen capture must be granted through a portal API.
For remote desktop, this creates a bootstrap problem. To share the screen, an application must ask the xdg-desktop-portal for a ScreenCast stream. To inject input, it must use the virtual-keyboard and virtual-pointer protocols. Historically, both required either a running interactive session or a one-time user prompt. If you wanted to connect to your computer from outside, there was no way to get that prompt without someone physically at the keyboard.
Various projects tried to solve this. GNOME Remote Desktop implemented a Wayland-native RDP server for GNOME, but it is tightly coupled to Mutter. KDE Plasma has similar built-in tools, and wlroots-based compositors like sway offer experimental solutions. But those are compositor-specific and lack the cross-platform, cross-desktop flexibility of a standalone tool like RustDesk.
What Changed in RustDesk: A Technical Look
RustDesk is an open-source, cross-platform remote desktop client known for its simplicity and end-to-end encryption. For a long time, its Linux version was X11-only. Users on Wayland could run RustDesk under XWayland, but that only worked if the compositor allowed XWayland applications to capture the screen. Many modern Wayland compositors restrict this, effectively blocking RustDesk.
The new Wayland backend in RustDesk is built on two pillars:
- Screen capture via PipeWire: RustDesk uses the ScreenCast interface of xdg-desktop-portal. It requests a persistent token that can be reused. With the user's one-time approval, the token allows RustDesk to start a ScreenCast session without any additional prompts, even after reboot.
- Input injection via Wayland Protocols: RustDesk implements the virtual-keyboard and virtual-pointer protocols. These protocols are part of the wayland-protocols package and are supported by KDE KWin (Plasma), wlroots compositors (sway, Hyprland, river), and Mutter (GNOME) in recent versions.
The critical piece for unattended access is that RustDesk runs a background service, rustdesk, which is independent of the user session. However, Wayland portals are per-session. RustDesk solves this by integrating with systemd user sessions and storing a portal permission file, so the service can access the ScreenCast API on behalf of the logged-in user.
Prerequisites
Before starting, make sure your system has:
- A supported Wayland compositor: KDE Plasma 5.27 or later, GNOME 43 or later, sway 1.8, Hyprland 0.30+, or other wlroots-based compositors from 2023+.
- PipeWire (1.0 or newer) and the pipewire session manager.
- The correct xdg-desktop-portal backend for your desktop environment.
- The latest RustDesk release (v1.3+ recommended; latest stable preferred).
- systemd with user lingering (optional but recommended for unattended access).
Here is a quick check you can run in your terminal:
pipewire --version
xdg-desktop-portal --version
If these commands return errors, install PipeWire and xdg-desktop-portal via your package manager. On Ubuntu/Debian, run:
sudo apt install pipewire pipewire-pulse xdg-desktop-portal xdg-desktop-portal-gnome
On Fedora:
sudo dnf install pipewire pipewire-utils xdg-desktop-portal xdg-desktop-portal-gnome
On Arch Linux:
sudo pacman -S pipewire xdg-desktop-portal xdg-desktop-portal-gnome
Then reboot or restart your compositor to ensure the portal services are running.
Step-by-Step Setup Guide
Step 1: Install RustDesk
Download the latest RustDesk package from the official website at rustdesk.com or the GitHub releases page. For Debian/Ubuntu, you can use wget to fetch the .deb package, then install it with dpkg. Replace the version string with the latest available. For example:
wget https://github.com/rustdesk/rustdesk/releases/latest/download/rustdesk-1.4.0-x86_64.deb
sudo dpkg -i rustdesk-1.4.0-x86_64.deb
sudo apt -f install
Alternatively, use distro-specific packages from community repos, such as the AUR on Arch Linux.
Step 2: Run RustDesk Manually
Launch RustDesk from your application menu. Since you are in a Wayland session, it should automatically detect Wayland. You'll see a window with a 9-digit ID and a temporary password. Click Settings -> Security. Set a permanent password to enable unattended access. Note that this password is stored in the RustDesk config and will be used by the background service.
Step 3: Enable the RustDesk Systemd Service
RustDesk ships a systemd unit file. To start the background service now and enable it at boot, run:
sudo systemctl enable rustdesk --now
If you are using a user-level installation (e.g., you compiled RustDesk yourself), you might need to create a user systemd unit:
systemctl --user enable rustdesk --now
To allow the user service to run even when no one is logged in (needed for unattended access), enable user lingering:
sudo loginctl enable-linger $USER
This ensures the RustDesk service starts automatically at boot and persists.
Step 4: Grant Persistent Portal Permission
After you have set the permanent password and the service is running, you must grant RustDesk permission to capture the screen. This is a one-time manual step. Launch the GUI one more time, then go to Settings and look for a "Wayland" section. There should be a button like "Allow capture" or "Configure portal." Click it.
A dialog from your desktop environment will appear, asking whether to allow RustDesk to capture the screen. Choose "Always allow" if available, or "Allow and remember". This creates a persisted permission entry in the xdg-desktop-portal database.
If you skip this step, unattended connections will fail because the portal will not have a matching permission. You can re-trigger the prompt by running rustdesk and clicking the button again.
Step 5: Test
From a remote machine (or a separate local user), open RustDesk, enter the ID of your Wayland machine, and type the permanent password. Click Connect. You should immediately get a desktop view. If you disconnect and reconnect, no prompt should appear on the remote screen.
To verify it is truly unattended, log out of the graphical session on the remote machine. The RustDesk service should still be running. Connect again — if you see a login screen or a lock screen, you may need to configure RustDesk to start on the greeter. Some users run a second RustDesk instance on the display manager to access the login screen.
Troubleshooting Common Issues
The table below lists frequent problems and their solutions.
| Issue | Likely Cause | Solution |
|---|---|---|
| "Screen capture not permitted" | Portal permission not granted or revoked | Relaunch RustDesk GUI and grant permission with "Always allow" |
| Black screen on remote client | PipeWire stream not started | Check systemctl --user status pipewire; install the correct portal backend |
| Mouse and keyboard do nothing | Compositor does not support virtual-pointer/keyboard protocols | Switch to KDE Plasma or wlroots compositor; check your compositor version |
| Connection works only with user at console | RustDesk service is not enabled in the user session | Run systemctl --user enable rustdesk and enable lingering |
| Login screen not visible | Wayland portals do not work on the greeter | Use a separate VNC or RDP service for the login screen |
For Hyprland users, an additional configuration is required. Add these lines to hyprland.conf to enable the virtual pointer and keyboard protocols:
windowrulev2 = noinitialfocus, class:^RustDesk$
misc:allow_virtual_keyboard = true
misc:allow_virtual_pointer = true
Note: The exact syntax depends on your Hyprland version. Refer to the official Hyprland wiki for the latest.
Comparison with Other Remote Solutions
To understand RustDesk's unique position, here is a comparison of popular Linux remote desktop tools and their Wayland support.
| Solution | Native Wayland Capture | Unattended Access | Compositor Agnostic |
|---|---|---|---|
| RustDesk | Yes (PipeWire + virtual input) | Yes (since 2026 stable) | Yes |
| GNOME Remote Desktop | Yes (RDP only) | Yes | No (GNOME only) |
| RealVNC | No | No | No |
| Sunshine + Moonlight | Yes (PipeWire) | No (requires stream start) | Partial |
| TigerVNC | No | No | No |
As the table shows, RustDesk is the only out-of-the-box solution that combines native Wayland capture with true unattended access and wide compositor support.
Performance and Security Considerations
Wayland screen capture via PipeWire is hardware-accelerated when the GPU driver supports DMA-BUF. That means lower CPU usage than X11 screen sharing. For remote desktop, you should also consider these security practices:
- Always generate a strong random password for unattended access. Avoid reusing passwords from other accounts.
- Enable end-to-end encryption. RustDesk does this by default, but verify that "Enable E2E" is checked in settings.
- If you expose your RustDesk server to the internet, use a firewall and consider running it behind a VPN or using a self-hosted RustDesk relay server.
- Update RustDesk regularly to get the latest security patches and Wayland protocol support.
- Monitor connection logs. RustDesk logs all login attempts; review them periodically.
For organizations that need to manage unattended access across many Wayland machines, RustDesk offers API-based provisioning and scripting. ASI Biont supports connecting to RustDesk via API — learn more at asibiont.com/courses.
Real-World Use Cases
With unattended Wayland access, several scenarios become practical:
- Remote sysadmin: Fix a GUI issue on a Linux workstation without asking the user to run a command.
- Home automation: Access your HTPC, smart display, or laptop from on the go.
- CI/CD testing: Automate GUI testing on Wayland by keeping a RustDesk service running on test runners.
- Education and support: Help a student or relative solve a problem even when they are away from the machine.
Sources
- RustDesk Official Documentation: https://rustdesk.com/docs/
- PipeWire ScreenCast Architecture: https://pipewire.org/docs/
- Wayland Protocols Specification: https://wayland.app/protocols/
- xdg-desktop-portal Documentation: https://flatpak.github.io/xdg-desktop-portal/
- RustDesk GitHub Repository: https://github.com/rustdesk/rustdesk
Conclusion
The arrival of true unattended remote access in RustDesk removes the last major barrier to using Wayland in production environments. With a one-time setup and a persistent portal permission, you can enjoy the security of Wayland without compromising on flexibility. This is not just a feature update; it's a fundamental shift in what is possible on Linux desktops.
Try it yourself on your Wayland machine. The future of remote access on Linux is here, and it's open-source.
Comments