xdg-desktop-portal-generic

Website · Documentation · Source

A generic XDG Desktop Portal backend for Wayland compositors.

Enables sandboxed applications (Flatpak, Snap) to access screen capture, input injection, clipboard, screenshots, and desktop settings on any Wayland compositor that implements standard ext- or wlr- protocols.

Connects as a standalone Wayland client -- no compositor-side code changes or custom traits required.

Developed by Lamco Development LLC as part of the lamco-rdp-server ecosystem.

Supported Portals

Protocols are auto-detected at startup. The best available protocol is selected automatically with ext- protocols preferred over wlr- equivalents.

Dependencies

Build dependencies:

• Rust >= 1.87
• libpipewire-0.3-dev
• libspa-0.2-dev
• libwayland-dev
• libxkbcommon-dev
• libclang-dev

Runtime:

• A Wayland compositor with ext- or wlr- protocol support
• PipeWire (for ScreenCast)
• xdg-desktop-portal (the frontend daemon)

Distro-Specific Packages

Debian/Ubuntu:

sudo apt install libpipewire-0.3-dev libspa-0.2-dev libwayland-dev \
    libxkbcommon-dev libclang-dev

Fedora:

sudo dnf install pipewire-devel wayland-devel libxkbcommon-devel clang-devel

Arch:

sudo pacman -S pipewire wayland libxkbcommon clang

Building

cargo build --release

Or use the Makefile:

make build

Installation

sudo make install

This installs:

To uninstall:

sudo make uninstall

Running

Environment Setup

Ensure your compositor exports the required environment variables into D-Bus:

dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP

Most compositors do this automatically.

Portal Configuration

Create a portal configuration file to tell xdg-desktop-portal which backend to use. Create ~/.config/xdg-desktop-portal/portals.conf (or the appropriate file for your XDG_CURRENT_DESKTOP):

[preferred]
default=gtk
org.freedesktop.impl.portal.RemoteDesktop=generic
org.freedesktop.impl.portal.ScreenCast=generic
org.freedesktop.impl.portal.Clipboard=generic
org.freedesktop.impl.portal.Settings=generic
org.freedesktop.impl.portal.Screenshot=generic

See the portal configuration docs for more information on the portals.conf format.

Automatic Activation

When correctly installed, xdg-desktop-portal will automatically activate xdg-desktop-portal-generic via D-Bus when an application requests a portal that is configured to use this backend.

Manual Startup

For development and testing, you can start it directly:

RUST_LOG=xdg_desktop_portal_generic=debug xdg-desktop-portal-generic

Configuration

All configuration is via environment variables, set before the service starts (e.g., in your compositor config or systemd override).

Appearance Settings

Input Protocol

External Tools

Source Picker Protocol

The source picker tool receives available sources on stdin as tab-separated lines (name\ttype\tid), one per line. It should output selected source names on stdout, one per line. Exit without output to cancel.

Example using fzf:

#!/bin/sh
fzf --multi --with-nth=1 --delimiter='\t' | cut -f1

Color Picker Protocol

The color picker tool receives a PNG screenshot path on stdin. It should output x y coordinates (space-separated integers) on stdout. The color at those coordinates will be returned to the requesting application.

Compatible Compositors

Designed for compositors that do not ship their own portal backend:

• COSMIC -- System76's desktop environment
• Niri -- Scrollable-tiling Wayland compositor
• Jay -- Tiling Wayland compositor
• Any Smithay-based compositor

Works with any compositor that implements ext- or wlr- Wayland protocols. The UseIn list in generic.portal can be extended for additional compositors.

Architecture

Three-thread model:

+--------------------+     mpsc channels     +----------------------+
| Tokio async runtime| <------------------> | Wayland event loop    |
| (main thread)      |                      | (dedicated thread)    |
|                    |                      |                      |
| - D-Bus service    |  Arc<Mutex<>> state  | - Protocol dispatch   |
| - Session mgmt     | <------------------> | - Frame capture       |
| - Portal logic     |                      | - Clipboard events    |
+--------------------+                      +----------------------+
        |                                            |
        |  PipeWire node IDs                        |  SHM buffers
        v                                            v
+--------------------+
| PipeWire thread    |
| - Stream mgmt     |
| - Buffer delivery  |
+--------------------+

1. Tokio async runtime (main) -- D-Bus service, session management, portal interface logic
2. Wayland event loop (dedicated thread) -- Wayland protocol dispatch, frame capture, clipboard data control
3. PipeWire thread -- Stream creation and management, SHM buffer delivery to consuming applications

Communication between threads uses mpsc channels for commands and Arc<Mutex<>> for shared state.

Debugging

Enable debug logging:

RUST_LOG=xdg_desktop_portal_generic=debug xdg-desktop-portal-generic

For trace-level output including protocol messages:

RUST_LOG=xdg_desktop_portal_generic=trace xdg-desktop-portal-generic

Useful Tools

• dbus-monitor -- Watch portal D-Bus requests:

  dbus-monitor --session "interface='org.freedesktop.impl.portal.ScreenCast'"
  

• busctl -- Inspect the D-Bus service:

  busctl --user introspect org.freedesktop.impl.portal.desktop.generic /
  

• portal-test -- Flatpak app for testing portal implementations
• pw-top -- Monitor active PipeWire streams during screen capture
• wayland-info -- List compositor globals and verify protocol support

Checking Protocol Support

To verify which protocols your compositor supports:

wayland-info | grep -E '(ext_image_copy_capture|zwlr_screencopy|ext_data_control|zwlr_data_control|wlr_virtual_pointer|zwp_virtual_keyboard)'

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

Licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.