Open Source › xdg-desktop-portal-generic
xdg-desktop-portal-generic
A generic XDG Desktop Portal backend for Wayland compositors — compositor-agnostic by design
Portal access, without compositor buy-in
xdg-desktop-portal is the Freedesktop spec that lets sandboxed applications (Flatpak, Snap, and increasingly native Wayland apps) ask for privileged capabilities — screen capture, remote-desktop input, clipboard access, screenshots — through a permission-mediated D-Bus interface. Most compositors ship their own backend implementation (xdg-desktop-portal-gnome, xdg-desktop-portal-kde, xdg-desktop-portal-wlr). A compositor that doesn’t have one can’t offer these capabilities to sandboxed apps.
xdg-desktop-portal-generic fills the gap for any compositor that implements standard ext- or wlr- Wayland protocols. It runs as a regular Wayland client — no compositor-side code changes, no custom traits, no forks. Auto-detects available protocols at startup and selects the best combination per requested portal.
Five portal interfaces
Each portal uses the best available protocol, with an automatic fallback when the preferred path isn’t present.
| Portal | Ver | Primary protocol | Fallback |
|---|---|---|---|
| RemoteDesktop | v2 | EIS (libei) bridge | wlr-virtual-pointer + zwp-virtual-keyboard |
| ScreenCast | v5 | ext-image-copy-capture-v1 | wlr-screencopy-v1 |
| Clipboard | v1 | ext-data-control-v1 | wlr-data-control-v1 |
| Settings | v2 | Environment variable config | GTK_THEME detection |
| Screenshot | v2 | Single-frame capture to PNG | — |
ext- protocols are preferred over wlr- equivalents when both are present.
Build, install, pick it as your backend
# Dependencies (Debian / Ubuntu):
sudo apt install libpipewire-0.3-dev libspa-0.2-dev libwayland-dev \
libxkbcommon-dev libclang-dev
# Build and install:
cargo build --release
sudo make install
# Installs binary, portal config, D-Bus service, systemd user unit.
[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
Once configured, xdg-desktop-portal auto-activates the generic backend via D-Bus when a sandboxed app requests one of the supported portals.
Configured via environment variables
All configuration is environment-variable-based — set once in your compositor config or systemd override, no config file to manage.
Appearance & accessibility
| Variable | Values | Default |
|---|---|---|
| XDP_GENERIC_COLOR_SCHEME | 0 / 1 / 2 (detect / dark / light) | 0 |
| XDP_GENERIC_ACCENT_COLOR | r,g,b floats | 0.21,0.52,0.89 |
| XDP_GENERIC_CONTRAST | 0 / 1 | 0 |
| XDP_GENERIC_REDUCED_MOTION | 0 / 1 | 0 |
Input protocol selection
| Variable | Values | Default |
|---|---|---|
| XDP_GENERIC_INPUT_PROTOCOL | eis / wlr | eis |
| XDP_GENERIC_INPUT_NO_FALLBACK | 1 | unset |
| XDP_GENERIC_EIS_SOCKET | path | auto |
External tools
| Variable | Description |
|---|---|
| XDP_GENERIC_SOURCE_PICKER | External tool for ScreenCast source selection UI — fzf, rofi, anything that speaks stdin/stdout |
| XDP_GENERIC_COLOR_PICKER | External tool for Screenshot color picking |
Where this fits
Designed for Wayland compositors that don’t ship their own portal backend.
Use it with
Don’t use it with
- — GNOME — use
xdg-desktop-portal-gnome - — KDE Plasma — use
xdg-desktop-portal-kde - — Sway / wlroots — use
xdg-desktop-portal-wlr - — X11 sessions — Wayland-only
Related work at Lamco
Adjacent — the Rust Wayland capture stack that consumes portals (rather than providing them).
Ecosystem — on compositors without a portal backend, pair Lamco RDP Server with this for screen capture.
Background — why portals exist and how they interact with capture.
Upstream — the frontend daemon this backend plugs into.