By stack
Apps built the same way break the same way. Find the app’s stack (the .deb’s
dependencies, readelf -d on the binary and strings usually tell), then go
through its list: what to put in the manifest and wrapper, and what to test
before the PR. Each item links to the page that explains it.
For agents
Electron
- Runtime
org.freedesktop.Platform,base: org.electronjs.Electron2.BaseAppat the same version; start withzypak-wrapper <binary> --ozone-platform-hint=auto "$@"(Folo). unset ELECTRON_RUN_AS_NODEin the wrapper. A few apps exit on anyELECTRON_*variable (VS Code’s terminal exportsELECTRON_NO_ATTACH_CONSOLE); clear them all for those. Test withenv -u ELECTRON_RUN_AS_NODE -u ELECTRON_NO_ATTACH_CONSOLE flatpak run …from an IDE terminal, or the test fails for a reason users never hit.StartupWMClass: measured; it is the product name (desktop integration).export TMPDIR="$XDG_RUNTIME_DIR/app/$FLATPAK_ID"in the wrapper if the app has a tray icon or plays media. Chromium writes the tray icon and the cover art to files in$TMPDIRand hands the desktop their paths, which the host can’t read in the sandbox’s private/tmp(tray placeholder).- Media:
--own-name=org.mpris.MediaPlayer2.chromium.*, if the app plays media (media controls). - Saved passwords on Hyprland and Sway:
--password-store=gnome-libsecret(keyrings). - Data in a
~/.dotdir(os.homedir()): grant it with:createor--persist(permissions). - A setuid
chrome-sandboxin a.deb: clear the bit (chmod -R a-s). - Seeding an electron-store config (to switch the updater off, say): it merges
with the defaults at the top level only, so
{"options":{"autoUpdates":false}}replaces the wholeoptionsobject and the app may not open. Seed the full block for the version shipped. - electron-builder
.debvs AppImage: the.debshipsresources/package-type, which makes electron-updater try to install.debupdates. The AppImage tree has no such file, and with noAPPIMAGEvariable set the updater stays off, so prefer the AppImage when upstream offers both (P3X OneNote).
Chromium-based browsers
- Same base and zypak as Electron, plus
CHROME_WRAPPER,ZYPAK_SPAWN_LATEST_ON_REEXEC=1andZYPAK_EXPOSE_WIDEVINE_PATH(zypak). - Check the profile directory name the browser really uses before pointing anything at it; branded builds differ from the main product.
StartupWMClassmeasured;CHROME_DESKTOPis ignored by branded builds.- User flags: read a
<name>-flags.conffrom the app’s config directory in the wrapper, the way native packages do.
Tauri (WebKitGTK)
- Runtime
org.gnome.Platform. Keep the.deb’susrtree whole when it hasusr/lib/<Name>/(Debian packages). - Rendering:
WEBKIT_DISABLE_DMABUF_RENDERER=1, unless the window istransparentor the app crashes on GNOME 51, then:-0. Grep the app’s startup code forWEBKIT_first: an app that sets the variable itself needs nothing from the wrapper (WebKitGTK). - Name the launcher symlink after the app id, and use it as
StartupWMClass(Flow). - Tray: Tauri’s own
TrayIconBuilderneeds theayatana-stackprebuilt andxdg-run/tray-icon:create, only if it really has a tray; an app that draws its tray withksnineeds neither, only the name grant (tray). - Clipboard plugin:
--socket=x11(copy and paste). - Single instance: grant
<identifier>.SingleInstance(second instance). - Updater plugin: can’t be turned off from outside (updaters).
- Use the
identifierintauri.conf.jsonas the app id.
Wails v3
- Links WebKitGTK 6 and GTK 4, so
org.gnome.Platformeven if the.debsays webkit2gtk-4.1. - Aborts at start unless the app’s
Linux.ApplicationIDis the Flatpak id (WebKitGTK 6). - Tray uses the unique connection name; only the watcher grant.
GPUI (Zed-style) and other cosmic-text apps
- A shipped
fonts.conflisting every font directory, andFONTCONFIG_FILEpointing at it (fonts). --talk-name=org.a11y.Bus(accessibility).--device=drifor GPU rendering.
Slint
- Check the Slint version in the binary first: up to 1.16 needs both the
fonts.confandSLINT_DEFAULT_FONT=<directory>; 1.17 and later needs onlySLINT_FONT_PATH=<directory>(fonts). SLINT_BACKEND=winit-softwareas a documented override for GPUs where rendering fails (meatshell).
Flutter
- Usually a relocatable bundle in a tarball; the freedesktop runtime is enough.
Tarballs often record a real uid:
--no-same-owner(Vynody). - A compiled GApplication id different from the Flatpak id needs
--own-name=<compiled id>, or the app exits silently (second instance). - Tray:
--own-name=org.fluttertray.*; MPRIS uses an app-id prefix unless the app hard-codes another one (MPRIS). - Any Dart
dbusclient on the system bus (nm,upower,bluezpackages) hangs without one; see system bus probes. - File associations: usually
%F; many Flutter apps don’t parsefile://URIs (opening files). - Fonts work through fontconfig; no
fonts.confneeded. - Links that never open:
url_launcher’scanLaunchUrlasks GIO for a defaulthttpshandler, and the sandbox has none, so apps that check beforelaunchUrlsilently do nothing (launchUrlalone works through the portal). Ship a privateNoDisplayhandler forx-scheme-handler/http;httpsoutside/app/share/applications, runupdate-desktop-databaseon it (GIO needs themimeinfo.cache), and prepend its directory toXDG_DATA_DIRSin the wrapper (Mornye).
Qt
- Prefer an AppImage that carries its own Qt on the freedesktop runtime over a
.deblinked to the system Qt (choosing a format). - Bundled Qt with only the
xcbplugin:--socket=x11,--unset-env=QT_QPA_PLATFORM,QT_QPA_PLATFORM="${QT_QPA_PLATFORM:-xcb}"(Mark Shot). - A bundled Qt may lack the portal platform theme; its file dialogs then see only the granted folders.
.NET
- Self-contained .NET 5 and older look for OpenSSL 1.1 and abort on a runtime
with only OpenSSL 3 (“No usable version of libssl”): the
openssl-1.1-compatprebuilt, appended last toLD_LIBRARY_PATH. Checktfmin<App>.runtimeconfig.json; .NET 6 and later don’t need it. - Never delete a file listed in
<App>.deps.json, even an unused native library: the host checks every entry at start and aborts if one is missing. - Avalonia tray:
--own-name=org.kde.*(tray).
Java
- Use the JRE upstream bundles, if it does; otherwise pin a JRE (Zulu, Temurin) as a second extra-data download and point the launcher at it.
user.homeis the real$HOME, not redirected: settings in a~/.appor~/.config/<app>directory need--persistor a grant (permissions).- An embedded Chromium (JxBrowser, JCEF) brings the nested-sandbox problem (embedded Chromium).
- HiDPI:
-Dsun.java2d.uiScalein the app’s options file, or the app’s own setting.
Windows apps (Wine)
- Packaged on Cellar:
the vendor’s Windows installer is the managed extra-data download, and
cellar-clia second, fixed one outside the managed block. Cellar runs the installer, unmodified, into the user’s prefix on first launch. - Wine is not bundled: it is
org.winehq.Winefrom Flathub, one install every Wine app shares. Grant its install paths read-only (~/.local/share/flatpak/app/org.winehq.Wine:roand/var/lib/flatpak/app/org.winehq.Wine:ro), keep the runtime on the version its branch is built on (stable-26.08on 26.08), and list it underrequires:inflatpark.yml. Cellar shows the install command in a dialog when it is missing. - Grant the folders the app works in (
xdg-musicfor a player), not home. - Redirect the prefix’s desktop folder into the sandbox, or installers drop shortcuts on the host’s desktop.
- Text in boxes in a WPF, CEF or Electron window while GDI text is fine: those
go through DirectWrite, which only sees fonts registered under
HKLM\Software\Microsoft\Windows NT\CurrentVersion\Fonts. Cellar registers the fonts it installs; a font copied intoC:\windows\Fontsby hand isn’t. - WPF falls back to a physical Arial and crashes in
TypefaceMapwithout one, so a WPF app’s prefix needs the Microsoft core fonts, not Liberation ([fonts] core = "microsoft"). If it flickers under wined3d, setHKCU\Software\Microsoft\Avalon.GraphicsDisableHWAcceleration=1. - Hebrew, Thai and Sinhala drawn as boxes under a CJK UI font is a Wine limit, not the package: GDI shapes complex scripts against the base font only and falls back to font linking just when the font lacks the script.
- Every Wine command against a prefix runs with that prefix’s
LC_ALL. Wine started under another locale rewrites the font-link defaults when its code page changes; the Flatpak’sLC_CTYPE=C.UTF-8alone means code page 1252.