Flatpak Permissions and Wayland Display Server

This article examines how Flatpak’s application sandboxing interacts with the Wayland display server in the Linux operating system. It details the permission models governing communication between sandboxed applications and the graphical subsystem, contrasts Wayland’s native isolation with legacy X11 behavior, and explains how XDG Desktop Portals bridge permission boundaries to handle privileged tasks like screen sharing and global shortcuts securely.

The Core Interaction: Sockets and Sandboxing

Flatpak isolates applications inside unprivileged containers using Linux kernel namespaces, cgroups, and Bubblewrap. By default, an isolated process cannot interact with the host’s graphical session or hardware. To render a graphical interface, the sandbox must be granted access to the display server's IPC (Inter-Process Communication) socket.

Flatpak manages this through specific socket permissions:

• --socket=wayland: Grants access strictly to the Wayland compositor’s socket (usually located in $XDG_RUNTIME_DIR/wayland-0).
• --socket=fallback-x11: A hybrid fallback that provides access to the legacy X11 socket only if the host is running an X11 session instead of Wayland.
• --socket=x11: Directly exposes the X11 server socket, allowing XWayland compatibility if the app cannot run natively on Wayland.

When an application is configured with --socket=wayland, Flatpak mounts the host's Wayland socket directly into the application's runtime environment, allowing the client to establish a direct protocol connection with the compositor.

Wayland’s Built-in Isolation Model

Under the traditional X11 windowing system, Flatpak's sandboxing guarantees were severely compromised. X11 lacks an internal security boundary; any client connected to the X11 socket can read the keystrokes directed at other windows, capture screens, inject input events, and manipulate arbitrary windows.

Wayland resolves this architectural flaw by enforcing strict client isolation at the protocol level:

1. Input Isolation: A Wayland client only receives input events (mouse clicks, keystrokes, touch inputs) when its specific surface has active focus. An application inside a Flatpak cannot log keystrokes destined for other applications.
2. Visual Isolation: Applications have no access to the global buffer or pixel data of other windows. An unprivileged application cannot record the screen or read window contents simply by having a Wayland connection.
3. Positional Privacy: Clients are unaware of their absolute position on the screen, the display resolution of other monitors, or the existence of other running windows.

Because Wayland's design is inherently defensive, granting an application --socket=wayland does not defeat the Flatpak sandbox. The application can only draw its own buffers and receive events specifically routed to it by the compositor.

Handling Privileged Actions with Portals

Because the Wayland core protocol explicitly prohibits actions like arbitrary screen capture, global hotkey interception, and remote desktop input, legitimate applications (such as OBS Studio, Discord, or accessibility tools) cannot perform these tasks using standard Wayland protocols alone.

To resolve this limitation without puncturing the sandbox, Flatpak and Wayland rely on XDG Desktop Portals (xdg-desktop-portal).

The interaction works through a three-party handshake:

1. D-Bus Request: The sandboxed Flatpak communicates via a filtered D-Bus session with the portal daemon running on the host.
2. User Consent: The portal daemon prompts the user via the desktop environment's native dialog (e.g., GNOME Shell or KDE Plasma) to explicitly choose a display, window, or authorize an action.
3. Capability Hand-off: For tasks like screen capture, the compositor generates a PipeWire media stream for the selected surface. The portal daemon passes an open file descriptor for this PipeWire stream back to the Flatpak application.

This mechanism ensures that the sandboxed application never gains persistent, broad access to the display server's internals. Permissions are granted per-action or per-session, keeping Wayland's strict isolation intact while maintaining modern desktop functionality.