flatpak-run man page

flatpak-run — Run an application or open a shell in a runtime

Synopsis

flatpak run [OPTION...] REF [ARG...]

Description

If REF names an installed application, flatpak runs the application in a sandboxed environment. Extra arguments are passed on to the application.

If REF names a runtime, a shell is opened in the runtime. This is useful for development and testing.

flatpak creates a sandboxed environment for the application to run in by mounting the right runtime at /usr and a writable directory at /var, whose content is preserved between application runs. The application itself is mounted at /app.

The details of the sandboxed environment are controlled by the application metadata and various options like --share and --socket that are passed to the run command: Access is allowed if it was requested either in the application metadata file or with an option and the user hasn't overridden it.

Options

The following options are understood:

-h, --help

Show help options and exit.

-v, --verbose

Print debug information during command processing.

--version

Print version information and exit.

--arch=ARCH

The architecture to install for.

--command=COMMAND

The command to run instead of the one listed in the application metadata.

--branch=BRANCH

The branch to use.

-d, --devel

Use the devel runtime that is specified in the application metadata instead of the regular runtime, and use a seccomp profile that is less likely to break development tools.

--runtime=RUNTIME

Use this runtime instead of the one that is specified in the application metadata. This is a full tuple, like for example org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any empty or missing parts are filled in with the corresponding values specified by the app.

--runtime-version=VERSION

Use this version of the runtime instead of the one that is specified in the application metadata. This overrides any version specified with the --runtime option.

--share=SUBSYSTEM

Share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--unshare=SUBSYSTEM

Don't share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--socket=SOCKET

Expose a well known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. This option can be used multiple times.

--nosocket=SOCKET

Don't expose a well known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. This option can be used multiple times.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--nodevice=DEVICE

Don't expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--allow=FEATURE

Allow access to a specific feature. This overrides to the Context section from the application metadata. FEATURE must be one of: devel, multiarch. This option can be used multiple times.

--disallow=FEATURE

Disallow access to a specific feature. This overrides to the Context section from the application metadata. FEATURE must be one of: devel, multiarch. This option can be used multiple times.

--filesystem=FS

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The optional :ro suffix indicates that the location will be read-only. The optional :create suffix indicates that the location will be read-write and created if it doesn't exist. This option can be used multiple times.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a homedir-relative path like ~/dir. This option can be used multiple times.

--add-policy=SUBSYSTEM.KEY=VALUE

Add generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:

[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

--remove-policy=SUBSYSTEM.KEY=VALUE

Remove generic policy option. This option can be used multiple times.

--env=VAR=VALUE

Set an environment variable in the application. This overrides to the Context section from the application metadata. This option can be used multiple times.

--own-name=NAME

Allow the application to own the well known name NAME on the session bus. If NAME ends with .*, it allows the application to own all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--talk-name=NAME

Allow the application to talk to the well known name NAME on the session bus. If NAME ends with .*, it allows the application to talk to all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-own-name=NAME

Allow the application to own the well known name NAME on the system bus. If NAME ends with .*, it allows the application to own all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-talk-name=NAME

Allow the application to talk to the well known name NAME on the system bus. If NAME ends with .*, it allows the application to talk to all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--persist=FILENAME

If the application doesn't have access to the real homedir, make the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, allowing that location to be used for persistent data. This overrides to the Context section from the application metadata. This option can be used multiple times.

--log-session-bus

Log session bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

--log-system-bus

Log system bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

Examples

$ flatpak run org.gnome.GEdit

$ flatpak run --devel --command=bash org.gnome.Builder

$ flatpak run --command=bash org.gnome.Sdk

See Also

flatpak(1), flatpak-override(1), flatpak-enter(1)

Referenced By

flatpak(1), flatpak-enter(1), flatpak-metadata(5), flatpak-override(1).

flatpak run