Portals: Using GTK+ in a Flatpak

The time is ripe for new ways to distribute and deploy desktop applications: between snappy, Flatpak, AppImage and others there are quite a few projects in this area.


Most of these projects involve some notion of sandboxing: isolating the application from the rest of the system.

Snappy does this by setting environment variables like XDG_DATA_DIRS, PATH, etc,  to tell apps where to find their ‘stuff’ and using app-armor to not let them access things they shouldn’t.

Flatpak takes a somewhat different approach: it uses bind mounts and namespaces to construct a separate view of the world for the app in which it can only see what it is supposed to access.

Regardless which approach you take to sandboxing, desktop applications are not very useful without access to the rest of the system.  So, clearly, we need to poke some holes in the walls of the sandbox, since we want apps to interact with the rest of the system.

The important thing to keep in mind is that we always want to give the user control over these interactions and in particular, control over the data that goes in and out of the sandbox.


The flatpak story for this has been portals. To quickly summarize: Portals are high-level (in the sense that they talk about concepts that are relevant to users) APIs that let sandboxed applications request access to resources outside. Portal calls will (almost) always involve user interaction (basically, a dialog).

We have talked about portals for quite a while, see for example this post by Allan from two years ago. Therefore,  I am very happy to announce that we now have first release of the portal infrastructure :

Note that the portal APIs themselves are desktop-neutral, and we have separated the implementation using GTK+ dialogs into their own module. We are also working on a qt/KDE  implementation.

The  APIs included in these releases cover a lot of basic things:

  • opening files
  • opening uris
  • printing
  • taking screenshots
  • notifications
  • inhibiting screen lock
  • network status
  • proxy information

Using portals in apps

The good news is that most of these will just work transparently in GTK+ applications, since GTK+ and GLib have suitable APIs that can be made to use the portals without any changes required from the sandboxed application. This support is already in place in the master branches; and will be in the 3.22 releases. We are working on a similar level of support for qt/KDE.

In detail, for opening files, you can use GtkFileChooserNative (a file chooser implementation that will also use a native Windows filechooser if you are on that platform). GtkFileChooserButton will do this for you, unless you manually set its dialog to something else. Certain things will not work with the portal, such as previews, or adding extra custom widgets.

For printing, use GtkPrintOperation (again a long-standing GTK+ api that will use a native Windows print dialog if you are on that platform).

For opening uris, use gtk_show_uri or g_app_info_launch_default_for_uri. We also added a new function that works slightly better in this context, gtk_show_uri_on_window().


As I said, most of the portals will just be transparently used by sandboxed GTK+ applications (provided they use GTK+ from git), but I’ve also written a portal-test application to try all the available portals.


All of the tests use the regular GTK+ APIs, with the exception of the Screenshot button. Since we don’t have a screenshooting API in GTK+, that button makes a direct D-Bus call to the portal. Here is how it looks in action:


Whats next ?

For the first release, we’ve focused on portals for toolkit-level functionality. There is obvously a long list of other system integration points that will need to be covered. High up on our list for the near future are access to devices like webcams and microphones, and pulseaudio. If you are interested, the list of issues has some more information.

Update: I’ve been asked: Why do I need a portal, the file chooser in the libreoffice flatpak seems to work just fine ?! Most of the current flatpaks are shipping with a relatively open sandbox configuration that allows the application full access to the host filesystem, or at least to your entire home directory. Portals enable applications to  function in a constrained sandbox that does not have this.

11 thoughts on “Portals: Using GTK+ in a Flatpak”

  1. Will users be asked to approve an application the first time it is launched? I’d like to see a list of the portals/credentials that an application will use, and then click [Approve] or [Close Application] depending on if I accept the list.

    Of course I’m a power user, so what I want may not be relevant to normal users.

  2. Several models are possible. Android recently moved from an everything-on-install model to a finer-grained model involving dialogs the first time an application requires a permission, which you can also deny.

    I believe it’s important to be able to deny a permission without completely stopping use of an application. I would also like the ability to hand out both persistent and one-time permissions. Just because I want the app to make a screenshot *now* doesn’t mean I want it to be able to do so in the background.

    Since Matthias talked about Portals always involving dialogs, I think the flatpak permission model is evolving in this way, which is a very nice development.

  3. My understanding is that it is a bit more organic where possible.

    For instance, when you request a file from the file system, the native file open dialog will open up:

    1. Choosing a file will result in an implicit permission to access the file.
    2. Pressing cancel will implicitly prevent the file being accessed.

    Now this model cannot work everywhere (for instance an image gallery), but it can solve a lot of interaction problems with dual dialogues or permission revocation.

  4. > it uses bind mounts and namespaces to construct a separate view of the world for the app

    When you open a file, does the application just get a file descriptor, or does the file get mounted into the application’s view of the filesystem somehow?

    1. When you open a file from outside the sandbox, using the file chooser portal, we make it available inside the sandbox via a fuse filesystem that gets mounted in $XDG_RUNTIME_DIR/doc.

  5. > We are working on a similar level of support for qt/KDE.
    Could you detail, who’s working on this?

  6. Most of the current flatpaks are shipping with a relatively open sandbox configuration[…]

    With “flatpaks”, do you mean flatpak the software or flatpak the package?

    Is the sandbox configuration part of the flatpak package (libre office) of part of the flatpack software itself?
    So current flatpak packages like libre office will not work with a properly configured flatpak software manager at some point?

    I’m really confused by the meaning of “flatpak” in this context :'(

    1. Flatpak as in application packages in this case.

      It should work just the same. But it will not give you the security that an updated package would since it’s configured to have full access.

      It’s really not something to worry about at this time.

Comments are closed.