Each application has a metadata file. This is a keyfile which provides information that is necessary to set up the sandbox for running the application.

A typical metadata file looks like this:

[Application]
name=org.gnome.gedit
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
command=gedit

[Context]
shared=ipc;network;
sockets=x11;wayland;pulseaudio;
devices=dri;
filesystems=host;

[Environment]
GEDIT_FOO=bar

[Session Bus Policy]
org.extra.name=talk
org.other.name=own

Flatpak currently requires the following keys in the Application group:

• name: The application id
• runtime: the name/arch/branch triple specifying the runtime that the application uses
• sdk: the name/arch/branch triple specifying the sdk that the application is built against
• command: the binary (in the application bundles files/bin directory) that is executed to run the application

Flatpak can use the following keys in the "Context" group

• shared: a list of subsystems that are shared with the host. Possible values:
  • network: share the network namespace with the host (see clone(2))
  • ipc: share the IPC namespace with the host (see clone(2)), mostly useful for X shared memory support
• sockets: a list of session sockets to give access to. Possible values:
  • x11: make the X server socket available to the application and set DISPLAY
  • wayland: make the Wayland socket available to the application
  • pulseaudio: make the pulseaudio socket and config files available to the application and set PULSEAUDIO_SERVER
  • system-bus: make the system bus socket available to the application and set DBUS_SYSTEM_BUS_ADDRESS
  • session-bus: make the unfiltered session bus socket available to the application and set DBUS_SESSION_BUS_ADDRESS
• devices: a list of devices to give access to
  • dri: make /dev/dri available to the application
• filesystems: grant access to a subset of the host system files
  • host: Allow access to all non-system host files
  • home: Allow full access to the users homedirectory
  • xdg-*: Allow access to one of the users configured user directories. Full list: xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-video.
  • Absolute path
  • Home-relative path such as ~/some/dir.
• persistent: List of files in the users homedirectory to make persistant (in the case the app has no access to the real home). This is done by creating the directory in the non-persistent homedirectory and bind-mounting it into the per-app persistant data directory.

Flatpak can override certain environment variables in the sandbox. This is useful e.g. for variables that point to plugin directories or similar paths that don't exist in the sandbox (or exist, but contain incompatible libraries). To override those variables add them to the [Environment] group as NAME=VALUE pair. When an empty value is set (i.e. GEDIT_FOO=) the variable will be unset in the sandbox environment.

Even if session-bus is not in the Context/sockets list the app can still connect to the session bus (if one is running), but in a filtered form. By default it can only own names on the bus that are the same as the application id, or with one extra level of name (i.e. "org.domain.app.extra"), but the [Session Bus Policy] group in the runtime or the application can extend this access to allow the app to see, talk to or even own other names.

Runtimes may also have a metadata file. It has the same general format as application metadata.

A typical example:

[Runtime]
name=org.gnome.Platform
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20

[Extension org.gnome.Platform.GL]
directory=lib/GL

[Extension org.gnome.Platform.Timezones]
directory=share/zoneinfo

[Extension org.gnome.Platform.Locale]
directory=share/gnome-sdk/locale
subdirectories=true

[Environment]
GTK_PLUGIN_PATH=/app/lib/gtk/plugins:/usr/lib/gtk/plugins

[Session Bus Policy]
org.freedesktop.portal.*=talk

The [Runtime] section contains fields that can be used to connect the runtime and its corresponding sdk (currently unused).

The [Extension *] sections define extension points for the runtime. The name in the runtime is used together with the arch and branch of the runtime to find a runtime which then gets mounted inside the sandbox, at the location specified by the directory key.

If the subdirectories key is set to true for an extension, it means that there is a whole family of extension points, one for each subdirectory of the specified directory in the runtime, and the name of the runtimes that get mounted at each one are derived by appending the subdirectory name to the name in the [Extension ] heading, separated by a period.

As an example, if there is a share/gnome-sdk/locale/de subdirectory in the runtime, and a org.gnome.Platform.Locale.de runtime is installed on the system, it will be mounted at that location.

Extensions are optional. If no matching runtime is installed, the extension point will simply not be populated in the sandbox.

Same as for applications it is possible to override environment variables for entire runtimes. The overrides for runtime environment variables are applied before application overrides, so if both runtime and application override the same environment variable the value in application metadata file wins.