Portals are a standardised framework allowing desktop applications to use resources outside of their sandbox. The file chooser portal, for example, opens a native file chooser on the host system. When the user selects a file, the application is granted access to that file.
Portals provide a range of common features to applications, including:
Opening a file with a file chooser
Opening URIs in other applications
Preventing the device from suspend/sleep/powering off
Portals originated from the Flatpak project, but are now a common Linux desktop standard with support from GNOME, KDE and Snapcraft. They are even used outside of sandboxes to provide a standardised API to common desktop features such as screenshots and screen casts on wayland.
Add the desktop interface to your snap
This interface gives your snap access to the portals.
Enable Portal support in your application.
GTK 3: turn on portal support in GTK 3 by setting the following environment variable:
Qt: often defaults to using portals, but you can enable it manually by changing the platform theme:
Set QT_QPA_PLATFORMTHEME=gtk3 on GTK based desktops and
Set QT_QPA_PLATFORMTHEME=flatpak and QT_QPA_FLATPAK_PLATFORMTHEME=kde for Qt based desktops.
Electron: portal support is present in the Electron file chooser.
Both the gnome extension and the kde-neon extension automatically enable portal support for GTK 3 and Qt applications on GTK-based desktops. If your snap uses either extension, you only need to do step 1.
It is recommended to use the file chooser portal instead of the home and removable-media interfaces for the following reasons:
The portal gives the user complete control over what exact files your application should access while the interfaces are all-or-nothing toggles.
The portal works with hidden files and folders in the home directory. If a user chooses a hidden file, the portal will give your application access to it. The home interface does not give your app access to hidden files and folders in the home directory for security reasons. Note that the home interface does give access to hidden files and folders elsewhere, just not in the home directory itself.
The portal works with removable-media out of the box. If a user chooses a file from a USB stick, your app will get access to it. The removable-media interface, however, does not auto-connect by default.
However, the file chooser portal works a bit differently than the home interface:
Files are fuse-mounted to /run/user/<uid>/doc/<hash>/ in order to give your application access to it. So the path your application sees is different from the path a user chose, even though both are the same file.
Support for selecting folders instead of files will only work on distributions using xdg-desktop-portal > 1.8.0.
Currently, the files are mounted even if your application has access to the file using another interface. See Improving XDG Desktop Support for the current status on fixing this issue.
org.freedesktop.portal.Flatpak.Spawn only works in a Flatpak. If your application needs to run arbitrary binaries on the host system, you can use classic confinement.
Portal support depends on the version of xdg-desktop-portal in the host system. Older versions do not support all portals. Repology shows what version of xdg-desktop-portal each distribution has and the portals NEWS file explains what portals each version supports.