x11vnc Wayland bridge with script listener for KDE Plasma on Wayland

As you have probably already noticed, classic x11vnc under Wayland is not just a matter of "start a service and connect". This x11vnc Wayland bridge is aimed exactly at that point.

The difference from simple VNC setups is not only that no normal X11 framebuffer is directly available under Wayland. The real point is that the image is obtained through the KDE portal and PipeWire setup, written into a rawfb file and then handed over to x11vnc. At the same time, mouse and keyboard input must be mapped back cleanly to the selected monitor area.

Requirements

- running graphical user session
- KDE Plasma on Wayland
- Python 3
- 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. Extract the files

VNCBRIDGE-DOWNLOAD

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

cd ~/Documents
unzip x11vnc-wayland-bridge.zip -d x11vnc-wayland-bridge
cd x11vnc-wayland-bridge

What matters is not just extracting 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 x11vnc python-dbus python-gobject gstreamer gst-plugin-pipewire pipewire wireplumber xdg-desktop-portal xdg-desktop-portal-kde socat

What matters here is not just x11vnc, but also:

- xdg-desktop-portal-kde for desktop sharing under KDE Plasma
- pipewire and gst-plugin-pipewire for screencast transport
- socat for the listener

3. 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_x11vnc_wayland_listener.sh from your bridge folder

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

4. 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

5. 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.

6. Confirm the portal selection

On the first connection, the KDE sharing dialog opens. Confirm the desired monitor or monitor selection there.

Internally this stores:

- the selection in pwfb.meta
- and the restore token in pwfb.restore_token

7. Enjoy

Once the selection has been stored, the setup can continue to work with the same selection later without starting from scratch every time.

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/x11vnc-wayland-bridge

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

- STATE_DIR
- RAWFB_PATH
- META_PATH
- TOKEN_FILE
- LISTEN_HOST
- LISTEN_PORT
- the fixed log files and their size limits

The default port in this setup is:

5900

The default state files live under:

~/.local/state/x11vnc-wayland-bridge

2. Clear the state cleanly if needed

If old selection or token files already exist and you deliberately want to start from a clean state, you can clear the state first:

./start_x11vnc_wayland_ondemand.sh --clear

This removes the files directly inside the state directory, including:

- pwfb.meta
- pwfb.restore_token
- the related log files

That is useful when:

- an old monitor selection no longer fits
- the first share should be rebuilt cleanly
- you deliberately want to force a fresh portal dialog

3. Start the listener

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

./start_x11vnc_wayland_listener.sh

Host and port can also be overridden directly at startup:

LISTEN_HOST=127.0.0.1 LISTEN_PORT=5901 ./start_x11vnc_wayland_listener.sh

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.

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
- start_x11vnc_wayland_ondemand.sh --inetd is started
- if pwfb.meta or pwfb.restore_token are missing, a new portal selection is prepared
- portal_rawfb_bridge.py opens the KDE screencast through the portal and PipeWire
- the image is written into the runtime rawfb file
- x11vnc reads exactly that rawfb file
- x11vnc_pipeinput.py translates pointer and keysym input back to Wayland cleanly

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

- portal selection
- PipeWire video
- rawfb
- x11vnc
- pipeinput helper

5. First connection and monitor selection

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

host:5900

On the first connection:

- if no stored selection exists yet, the KDE sharing dialog opens automatically
- the chosen selection is stored in pwfb.meta
- the restore token is stored in pwfb.restore_token

After that the setup tries to map the selected outputs back to the current geometry from xrandr or KDE.

An extra point that matters in this project:

- the incoming connection first tries to wake the selected monitor
- if the monitor is sleeping, the session waits for dpms=On

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

6. Logs and troubleshooting

In practice it is helpful that the components are logged separately. The setup writes fixed log files with size limits so that everything does not end up mixed in one file.

Useful commands include:

tail -f ~/.local/state/x11vnc-wayland-bridge/listener.log
tail -f ~/.local/state/x11vnc-wayland-bridge/inetd.log
tail -f ~/.local/state/x11vnc-wayland-bridge/bridge.log
tail -f ~/.local/state/x11vnc-wayland-bridge/pipeinput.log

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

- the listener does not accept the connection
- portal selection or restore token is missing
- PipeWire does not deliver a stream
- monitor geometry does not match
- pointer or keyboard mapping is off

7. Rebuild the selection if needed

If the stored selection exists in principle but should deliberately be rewritten, --reseed is the clean way:

./start_x11vnc_wayland_ondemand.sh --reseed

This discards the old selection and prepares the portal part again. That is useful when:

- monitors have been changed
- the old mapping no longer matches the current geometry
- a new restore token should be generated

8. Result

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

- x11vnc can still be used despite Wayland
- screen sharing runs through the KDE portal and PipeWire stack
- monitor selection persists through state files and restore tokens
- mouse and keyboard are mapped back cleanly through the pipeinput helper
- connections can be accepted through a simple script listener

This is not a minimal one-file setup, but deliberately a small bridge made of several components. Especially for KDE Plasma on Wayland, that exact structure can make sense if x11vnc should continue to be used without falling back to a classic X11 setup.