Clipboard, secrets and system services
Apps reach many desktop services through the session bus or a socket, and the sandbox passes on only what the package grants. A missing grant rarely shows as an error: paste does nothing, a password isn’t saved, a recording fails with a vague message. The fixes below are grants and launch flags; none of them change the app.
For agents
Copy and paste
| Symptom | Cause | Fix |
|---|---|---|
A Tauri app with tauri-plugin-clipboard-manager can’t paste or copy images; text may work or not |
The plugin uses arboard, which tries Wayland’s data-control protocol first. Flatpak’s Wayland socket filters privileged protocols, data-control included, so arboard falls back to X11, and --socket=fallback-x11 withholds X11 on a Wayland session |
--socket=x11 instead of fallback-x11. The window stays Wayland-native |
A Tauri app with the third-party tauri-plugin-clipboard exits at start with DisplayNotSet |
That plugin opens an X11 display when it starts and panics without one | --socket=x11 |
| An egui app pastes text but not images | egui’s text clipboard uses the plain Wayland data device; only images go through arboard | fallback-x11 can stay; document --socket=x11 as an override |
Check the app’s src-tauri/Cargo.toml for a clipboard crate before choosing
the socket, and verify with
flatpak run --command=sh <app-id> -c 'echo $DISPLAY' (empty means no X11).
This is not compositor-specific; the same build behaves the same everywhere.
Saved passwords and keyrings
- Secret Service (
org.freedesktop.secrets, served by GNOME Keyring or KWallet) is how sandboxed apps store secrets:--talk-name=org.freedesktop.secrets. - Electron and Chromium on an unrecognised desktop (Hyprland, Sway, …):
safeStoragepicks its backend fromXDG_CURRENT_DESKTOP, falls back to plain text, and reports “Encryption is not available”, so saving a password fails even with the grant. A native install behaves the same. Pass--password-store=gnome-libsecretfrom the wrapper on desktops other than KDE, unless the user already passed one (Min’s wrapper does this). - The kernel keyring (
keyctl,add_key; the Rustkeyringcrate’slinux-nativebackend) is blocked by Flatpak’s seccomp filter. An app using only that backend can’t store secrets in a Flatpak; the fix is upstream switching to Secret Service. - When testing, look for a new item over Secret Service and delete test items afterwards.
Screen capture and recording
- Screenshots and screen sharing go through the Screenshot and ScreenCast portals and need no grant. The user’s answers are kept in the permission store.
- An app that records the PipeWire node by connecting to the default PipeWire
socket itself (for example by spawning
gst-launch-1.0 pipewiresrc path=<node>) rather than through the fd the portal hands out needs--filesystem=xdg-run/pipewire-0(XerahS). That grant also opens every camera and other apps’ video streams, so it is declared as high-risk; an app that uses the portal’s fd doesn’t need it (the PipeWire socket). - The runtime’s FFmpeg has no
-f pipewireinput; an app that needs one records through GStreamer instead. - Apps that capture by their own X11 calls get only XWayland windows; a Wayland desktop needs the portal path.
Accessibility
Apps built on AccessKit (GPUI and many Rust toolkits) ask org.a11y.Bus where
the accessibility bus is. Without --talk-name=org.a11y.Bus screen readers
don’t see the window. Grant it when the binary carries org.a11y.atspi or
accesskit symbols (Navop).
Apps that probe the system bus
Flatpak mounts the system bus socket only when the package grants at least one
--system-talk-name. Without it, /var/run/dbus/system_bus_socket doesn’t
exist, and some D-Bus clients fail in a way the app can’t catch. The Dart
dbus package raises the connect error inside a signal subscription, outside
the caller’s try, so await NetworkManagerClient().connect() never
completes and whatever waited on it stalls.
PiliPlus
asks NetworkManager whether the link is metered before loading each video,
and videos stayed on the cover image.
Any --system-talk-name mounts the socket, so there are two fixes:
- Grant the service the app asks
(
--system-talk-name=org.freedesktop.NetworkManager), when its answer drives a feature. PiliPlus does this to pick the mobile-data quality on a metered link. Say in the comment what the app gets: NetworkManager exposes every connection’s name, Wi-Fi SSIDs and VPN profiles. - Grant a name nobody owns (
--system-talk-name=org.flatpark.Placeholder), when the app only reads a hint and has a fallback. The proxy mounts the socket, the call fails with an ordinary D-Bus error, and the fallback runs without the app seeing anything on the system bus.
The log shows SocketException … address = /var/run/dbus/system_bus_socket
with DBusClient._openSocket in the trace.
Commands on the host
An app that needs a host program (git, lsof, a CLI it manages) can’t run it
from the sandbox. A small script on PATH that runs the real command with
flatpak-spawn --host works, at the cost of --talk-name=org.freedesktop.Flatpak,
which lets the app run anything on the host: declare it as host-command and
argue for it in the PR (permissions).
Keep detection inside the sandbox: an app that checks whether a tool is
installed should see the sandbox’s answer, and only the actual run goes to the
host.
Things that don’t work from a Flatpak however it is granted: seeing host
processes (pgrep, /proc), and launching at login through the app’s own
autostart file.