vnc-wayland with script listener for KDE Plasma on Wayland

As you have probably already noticed, remote desktop under Wayland is not just a matter of "start a service and connect". The vnc-wayland setup is aimed exactly at that point.

The difference from classic setups is not only that no normal X11 framebuffer is directly available under Wayland. The real point is that krfb itself performs the screen capture and the input handling through the KDE portal and PipeWire - no rawfb file, no separate x11vnc process. The only remaining job is a small listener that accepts the VNC connection, wakes a sleeping display, and forwards the connection to the internal krfb port.

Requirements

- running graphical user session
- KDE Plasma on Wayland
- systemd --user for the short-lived krfb scope
- working xdg-desktop-portal-kde and PipeWire setup
- socat for the listener
- a VNC client for the connection

Part 1: Quick start

If you just want to get the setup running, the practical flow is basically this:

1. Get the project

vnc-wayland on GitHub

First place the project where it will actually be used later, for example:

cd ~/Documents git clone https://github.com/urpid/vnc-wayland.git cd vnc-wayland

Then make the two startup scripts executable:

chmod +x start_krfb_wayland_ondemand.sh chmod +x start_krfb_wayland_listener.sh

What matters is not just getting the files, but making sure they end up under a fixed path. The scripts and the optional systemd --user variant refer to exactly that directory.

2. Install dependencies

Install the required packages first:

sudo pacman -S --needed krfb qt6-tools pipewire wireplumber xdg-desktop-portal xdg-desktop-portal-kde socat iproute2 procps-ng systemd

What matters here is not only pipewire and xdg-desktop-portal-kde for desktop sharing under KDE Plasma, but also socat for the listener.

Important: do not install krfb through that line. Since version 26.07 the main krfb binary no longer binds its VNC port - RfbServer::start() only calls listen when the internal passwordSet flag is set, which plain krfb never sets. The port therefore stays closed and every VNC connection waits 60 seconds before it fails. The cause is krfb commit 842c91e (April 2026, BUG 497071), still unfixed on master.

That is why the project pins krfb 26.04.3, the last version without the bug. The pinned package ships inside the repository, under packages/:

sudo pacman -U packages/krfb-26.04.3-1-x86_64.pkg.tar.zst pkill -x krfb

To keep pacman -Syu from upgrading krfb by accident, add IgnorePkg = krfb to /etc/pacman.conf.

Note that IgnorePkg only blocks pacman -Syu, not explicit pacman -S krfb calls. The package line above is therefore the only safe way to install krfb from now on.

Check the health of the pin:

pacman -Q krfb    # => krfb 26.04.3-1 ss -ltnp 'sport = :5901'   # after starting krfb: a LISTEN entry must be there

As soon as upstream fixes the bug: remove IgnorePkg = krfb from /etc/pacman.conf and update krfb with pacman -Syu.

3. Set up krfb once

Before the listener can start krfb automatically, krfb has to be configured once:

./start_krfb_wayland_ondemand.sh --setup

The setup command first deletes the existing portal restore token of krfb. Setup and the automatic starts run under the portal application identity org.kde.krfb, so the KDE portal generates a new token that krfb reuses on its automatic restarts.

The current KDE portal offers no monitor selection for the krfb remote desktop session. With several monitors, krfb transmits the entire work area.

In krfb:

- enable sharing of the work area
- allow control by mouse and keyboard

After that, close the krfb window with X. In setup mode, that terminates the process completely. When the listener later starts krfb on its own, it runs in the tray without the main window.

4. Add it to autostart

So that the listener is ready automatically after login, the startup script should be added through the KDE graphical autostart settings.

The practical path is:

- open System Settings
- go to Autostart
- open Add New
- choose Login Script...
- select start_krfb_wayland_listener.sh from your project folder

The only important point is that you select the listener script from the exact folder where you will actually use the setup later.

5. Restart or log in again

Then restart the graphical session once or log out and back in cleanly.

The reason is simple:

- portal, PipeWire and the user session should be in a clean state
- the listener should start directly through autostart

While the session restarts, take care of the firewall if needed. krfb binds its internal port to all network addresses, so port 5901 must stay blocked from outside; only the wake listener on 5900 should be reachable. If ufw is active:

sudo ufw allow 5900/tcp sudo ufw deny 5901/tcp

6. Establish the connection

Then connect with a VNC client to the host and port:

host:5900

If LISTEN_HOST or LISTEN_PORT were changed, then of course the modified port applies.

On the first connection the VNC password of the krfb session is required. The portal part runs in the background: the restore token created during setup is reused, so the sharing is not rebuilt from scratch. As mentioned, the current portal offers no monitor selection - with multiple monitors the entire work area is transmitted.

7. Enjoy

Once krfb has run once with a valid portal token, the setup can continue to work with the same configuration later without starting from scratch every time. Every new VNC connection is accepted by the listener, the display is woken if needed, and krfb is restarted when a fresh PipeWire session is required.

Part 2: What the setup does internally and how to operate it cleanly

1. Change into the folder and know the central variables

Then change into the project directory:

cd ~/Documents/vnc-wayland

The central configuration lives in load-vars.sh. Among other things it defines:

- LISTEN_HOST (default 0.0.0.0)
- LISTEN_PORT (default 5900)
- KRFB_HOST (default 127.0.0.1)
- KRFB_PORT (default 5901)
- KRFB_UNIT (default krfb-wayland-server.service)
- KRFB_START_TIMEOUT (default 60)
- POLL_INTERVAL and WAKE_RETRY_EVERY for the wake loop

The public listener port in this setup is:

5900

The internal krfb port that the listener forwards to is:

5901

There is no separate state directory with rawfb files. The only state that matters is the portal restore token, which krfb itself stores in its own configuration (krfbstaterc, group XdgPortal, key RestoreToken).

2. Reset the setup cleanly if needed

If the portal token is stale, krfb was upgraded by mistake, or you deliberately want to start from a clean state, run the setup once more:

./start_krfb_wayland_ondemand.sh --setup

This stops a running krfb, reconfigures port 5901, deletes the portal restore token, loads the KWin close watcher and starts krfb with the dialog again.

If krfb had been upgraded by mistake, reinstall the pinned package first:

sudo pacman -U packages/krfb-26.04.3-1-x86_64.pkg.tar.zst pkill -x krfb

That is useful when:

- the old portal token no longer fits
- the first share should be rebuilt cleanly
- krfb is on the wrong version after an upgrade

3. Start the listener

If the requirements are met, the listener can be started like this:

./start_krfb_wayland_listener.sh

Host and port can also be overridden directly at startup:

LISTEN_HOST=127.0.0.1 LISTEN_PORT=5902 ./start_krfb_wayland_listener.sh

The internal krfb port stays 5901 in that case. The listener does not perform the Wayland sharing itself. It only listens for incoming connections and starts the same on-demand path internally for each real connection. Each accepted connection runs krfb in a short-lived systemd --user scope under the portal application identity org.kde.krfb, so the portal always sees the same application.

As an alternative, the project ships a systemd --user variant with krfb-wayland.socket on port 5900, krfb-wayland-server.service and the per-connection krfb-wayland@.service. The units link the project through the fixed path ~/.local/lib/krfb-wayland, so the repository itself can live anywhere:

mkdir -p ~/.local/lib ~/.config/systemd/user ln -sfnT "$PWD" ~/.local/lib/krfb-wayland ln -sf ~/.local/lib/krfb-wayland/krfb-wayland-server.service ~/.config/systemd/user/krfb-wayland-server.service ln -sf ~/.local/lib/krfb-wayland/krfb-wayland.socket ~/.config/systemd/user/krfb-wayland.socket ln -sf ~/.local/lib/krfb-wayland/krfb-wayland@.service ~/.config/systemd/user/krfb-wayland@.service systemctl --user daemon-reload systemctl --user enable --now krfb-wayland.socket

4. What happens internally during a connection

The real advantage of this setup is not just that it listens on port 5900, but how the connection is assembled internally.

Once a VNC client connects, the following happens in simplified form:

- socat accepts the connection
- the script always sends a wake pulse against a possible display dimming
- if at least one active monitor was in DPMS standby, the script waits until all active monitors report DPMS On
- after a standby, the script restarts krfb so that a fresh PipeWire session is created
- before a restart, the script stops krfb cleanly over D-Bus, so the current portal restore token is saved; only if that does not work, TERM and then KILL follow
- if no monitor was in standby, krfb is started only if its internal port is not available
- socat forwards the untouched VNC connection to krfb on 127.0.0.1:5901
- screen capture as well as mouse and keyboard input run entirely through krfb and the KDE portal

So the point is not just "VNC on Wayland", but the complete chain of:

- portal restore token
- PipeWire screencast
- krfb
- VNC on the internal port
- listener with wake handling

5. First connection and monitor handling

Then connect with your VNC client to the host and port:

host:5900

On the first connection:

- the VNC password of the krfb session is required
- the portal part runs in the background with the stored restore token
- the current portal offers no monitor selection; with multiple monitors the entire work area is transmitted

An extra point that matters in this project:

- the incoming connection first tries to wake the display
- if a monitor is sleeping, the connection waits for DPMS On
- the wake check covers all connected and enabled DRM outputs

This is useful because the setup does not blindly assume an old state, but resolves the actual current display state again.

6. Logs and troubleshooting

In practice it is helpful that the components are checked separately. When the listener is started manually, it writes directly to the terminal. Every accepted VNC connection is logged with the timestamp, the client address, the start mode and the state of all DRM outputs before the wake command.

Useful status commands include:

pgrep -af start_krfb_wayland_listener.sh pgrep -a -x krfb ss -ltnp 'sport = :5900' ss -ltnp 'sport = :5901'

When the listener is started through Plasma autostart, those entries are in the journal:

journalctl --user -u This email address is being protected from spambots. You need JavaScript enabled to view it.'

For the systemd variant:

systemctl --user status krfb-wayland.socket systemctl --user status krfb-wayland-server.service journalctl --user -u 'krfb-wayland@*'

This is especially important on Wayland because problems can appear at very different points:

- the listener does not accept the connection
- port 5900 is already occupied by another process
- krfb does not open port 5901 (wrong version - check the pin)
- the portal token is missing or stale
- the monitor is still sleeping after the wake attempt
- the firewall blocks the connection

7. Rebuild the setup if needed

If the stored portal token exists in principle but should deliberately be rewritten, running --setup again is the clean way:

./start_krfb_wayland_ondemand.sh --setup

This discards the old restore token, reconfigures the port and prepares the portal part again. That is useful when:

- monitors have been changed
- krfb was upgraded by mistake
- a new restore token should be generated

8. Result

If everything is prepared correctly, this setup provides exactly the benefit it is meant for:

- krfb can be used despite Wayland, with screen capture and input handled entirely through the KDE portal
- the pin to 26.04.3 keeps the VNC port reliably open
- the wake listener accepts connections and wakes sleeping displays before forwarding to krfb
- no rawfb file, no x11vnc and no pipeinput helper - the whole chain is shorter and closer to the desktop itself

This is not a minimal one-file setup, but deliberately a small project made of a listener, a setup script and the pinned krfb package. Especially for KDE Plasma on Wayland, that exact structure can make sense if the desktop's own remote framework should continue to be used without falling back to a classic X11 setup.