1FLATPAK RUN(1)                    flatpak run                   FLATPAK RUN(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

12       If REF names an installed application, flatpak runs the application in
13       a sandboxed environment. Extra arguments are passed on to the
14       application.
15
16       If REF names a runtime, a shell is opened in the runtime. This is
17       useful for development and testing.
18
19       By default, flatpak will look for the application or runtime in all
20       per-user and system installations. This can be overridden with the
21       --user, --system and --installation options.
22
23       flatpak creates a sandboxed environment for the application to run in
24       by mounting the right runtime at /usr and a writable directory at /var,
25       whose content is preserved between application runs. The application
26       itself is mounted at /app.
27
28       The details of the sandboxed environment are controlled by the
29       application metadata and various options like --share and --socket that
30       are passed to the run command: Access is allowed if it was requested
31       either in the application metadata file or with an option and the user
32       hasn't overridden it.
33
34       The remaining arguments are passed to the command that gets run in the
35       sandboxed environment. See the --file-forwarding option for handling of
36       file arguments.
37
38       Environment variables are generally passed on to the sandboxed
39       application, with certain exceptions. The application metadata can
40       override environment variables, as well as the --env option. Apart from
41       that, Flatpak always unsets or overrides the following variables, since
42       their session values are likely to interfere with the functioning of
43       the sandbox:
44           PATH
45           LD_LIBRARY_PATH
46           XDG_CONFIG_DIRS
47           XDG_DATA_DIRS
48           SHELL
49           TMPDIR
50           PYTHONPATH
51           PERLLIB
52           PERL5LIB
53           XCURSOR_PATH
54
55       Flatpak also overrides the XDG environment variables to point sandboxed
56       applications at their writable filesystem locations below
57       ~/.var/app/$APPID/:
58           XDG_DATA_HOME
59           XDG_CONFIG_HOME
60           XDG_CACHE_HOME
61
62       The host values of these variables are made available inside the
63       sandbox via these HOST_-prefixed variables:
64           HOST_XDG_DATA_HOME
65           HOST_XDG_CONFIG_HOME
66           HOST_XDG_CACHE_HOME
67
68       Flatpak sets the environment variable FLATPAK_ID to the application ID
69       of the running app.
70

OPTIONS

72       The following options are understood:
73
74       -h, --help
75           Show help options and exit.
76
77       --user
78           Look for the application and runtime in per-user installations.
79
80       --system
81           Look for the application and runtime in the default system-wide
82           installations.
83
84       --installation=NAME
85           Look for the application and runtime in the system-wide
86           installation specified by NAME among those defined in
87           /etc/flatpak/installations.d/. Using --installation=default is
88           equivalent to using --system.
89
90       -v, --verbose
91           Print debug information during command processing.
92
93       --ostree-verbose
94           Print OSTree debug information during command processing.
95
96       --arch=ARCH
97           The architecture to install for.
98
99       --command=COMMAND
100           The command to run instead of the one listed in the application
101           metadata.
102
103       --cwd=DIR
104           The directory to run the command in. Note that this must be a
105           directory inside the sandbox.
106
107       --branch=BRANCH
108           The branch to use.
109
110       -d, --devel
111           Use the devel runtime that is specified in the application metadata
112           instead of the regular runtime, and use a seccomp profile that is
113           less likely to break development tools.
114
115       --runtime=RUNTIME
116           Use this runtime instead of the one that is specified in the
117           application metadata. This is a full tuple, like for example
118           org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
119           empty or missing parts are filled in with the corresponding values
120           specified by the app.
121
122       --runtime-version=VERSION
123           Use this version of the runtime instead of the one that is
124           specified in the application metadata. This overrides any version
125           specified with the --runtime option.
126
127       --share=SUBSYSTEM
128           Share a subsystem with the host session. This overrides the Context
129           section from the application metadata.  SUBSYSTEM must be one of:
130           network, ipc. This option can be used multiple times.
131
132       --unshare=SUBSYSTEM
133           Don't share a subsystem with the host session. This overrides the
134           Context section from the application metadata.  SUBSYSTEM must be
135           one of: network, ipc. This option can be used multiple times.
136
137       --socket=SOCKET
138           Expose a well known socket to the application. This overrides to
139           the Context section from the application metadata.  SOCKET must be
140           one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
141           session-bus, ssh-auth, pcsc. This option can be used multiple
142           times.
143
144       --nosocket=SOCKET
145           Don't expose a well known socket to the application. This overrides
146           to the Context section from the application metadata.  SOCKET must
147           be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
148           session-bus, ssh-auth, pcsc. This option can be used multiple
149           times.
150
151       --device=DEVICE
152           Expose a device to the application. This overrides to the Context
153           section from the application metadata.  DEVICE must be one of: dri,
154           kvm, all. This option can be used multiple times.
155
156       --nodevice=DEVICE
157           Don't expose a device to the application. This overrides to the
158           Context section from the application metadata.  DEVICE must be one
159           of: dri, kvm, all. This option can be used multiple times.
160
161       --allow=FEATURE
162           Allow access to a specific feature. This overrides to the Context
163           section from the application metadata.  FEATURE must be one of:
164           devel, multiarch, bluetooth. This option can be used multiple
165           times.
166
167           See flatpak-build-finish(1) for the meaning of the various
168           features.
169
170       --disallow=FEATURE
171           Disallow access to a specific feature. This overrides to the
172           Context section from the application metadata.  FEATURE must be one
173           of: devel, multiarch, bluetooth. This option can be used multiple
174           times.
175
176       --filesystem=FILESYSTEM
177           Allow the application access to a subset of the filesystem. This
178           overrides to the Context section from the application metadata.
179           FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents,
180           xdg-download, xdg-music, xdg-pictures, xdg-public-share,
181           xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache,
182           xdg-data, an absolute path, or a homedir-relative path like ~/dir
183           or paths relative to the xdg dirs, like xdg-download/subdir. The
184           optional :ro suffix indicates that the location will be read-only.
185           The optional :create suffix indicates that the location will be
186           read-write and created if it doesn't exist. This option can be used
187           multiple times.
188
189       --nofilesystem=FILESYSTEM
190           Remove access to the specified subset of the filesystem from the
191           application. This overrides to the Context section from the
192           application metadata.  FILESYSTEM can be one of: home, host,
193           xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
194           xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a
195           homedir-relative path like ~/dir. This option can be used multiple
196           times.
197
198       --add-policy=SUBSYSTEM.KEY=VALUE
199           Add generic policy option. For example,
200           "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
201           map to this metadata:
202
203               [Policy subsystem]
204               key=v1;v2;
205
206
207           This option can be used multiple times.
208
209       --remove-policy=SUBSYSTEM.KEY=VALUE
210           Remove generic policy option. This option can be used multiple
211           times.
212
213       --env=VAR=VALUE
214           Set an environment variable in the application. This overrides to
215           the Context section from the application metadata. This option can
216           be used multiple times.
217
218       --own-name=NAME
219           Allow the application to own the well known name NAME on the
220           session bus. If NAME ends with .*, it allows the application to own
221           all matching names. This overrides to the Context section from the
222           application metadata. This option can be used multiple times.
223
224       --talk-name=NAME
225           Allow the application to talk to the well known name NAME on the
226           session bus. If NAME ends with .*, it allows the application to
227           talk to all matching names. This overrides to the Context section
228           from the application metadata. This option can be used multiple
229           times.
230
231       --no-talk-name=NAME
232           Don't allow the application to talk to the well known name NAME on
233           the session bus. If NAME ends with .*, it allows the application to
234           talk to all matching names. This overrides to the Context section
235           from the application metadata. This option can be used multiple
236           times.
237
238       --system-own-name=NAME
239           Allow the application to own the well known name NAME on the system
240           bus. If NAME ends with .*, it allows the application to own all
241           matching names. This overrides to the Context section from the
242           application metadata. This option can be used multiple times.
243
244       --system-talk-name=NAME
245           Allow the application to talk to the well known name NAME on the
246           system bus. If NAME ends with .*, it allows the application to talk
247           to all matching names. This overrides to the Context section from
248           the application metadata. This option can be used multiple times.
249
250       --system-no-talk-name=NAME
251           Don't allow the application to talk to the well known name NAME on
252           the system bus. If NAME ends with .*, it allows the application to
253           talk to all matching names. This overrides to the Context section
254           from the application metadata. This option can be used multiple
255           times.
256
257       --persist=FILENAME
258           If the application doesn't have access to the real homedir, make
259           the (homedir-relative) path FILENAME a bind mount to the
260           corresponding path in the per-application directory, allowing that
261           location to be used for persistent data. This overrides to the
262           Context section from the application metadata. This option can be
263           used multiple times.
264
265       --log-session-bus
266           Log session bus traffic. This can be useful to see what access you
267           need to allow in your D-Bus policy.
268
269       --log-system-bus
270           Log system bus traffic. This can be useful to see what access you
271           need to allow in your D-Bus policy.
272
273       -p, --die-with-parent
274           Kill the entire sandbox when the launching process dies.
275
276       --file-forwarding
277           If this option is specified, the remaining arguments are scanned,
278           and all arguments that are enclosed between a pair of '@@'
279           arguments are interpreted as file paths, exported in the document
280           store, and passed to the command in the form of the resulting
281           document path. Arguments between '@@u' and '@@' are considered
282           uris, and any file: uris are exported. The exports are
283           non-persistent and with read and write permissions for the
284           application.
285

EXAMPLES

287       $ flatpak run org.gnome.gedit
288
289       $ flatpak run --devel --command=bash org.gnome.Builder
290
291       $ flatpak run --command=bash org.gnome.Sdk
292

SEE ALSO

294       flatpak(1), flatpak-override(1), flatpak-enter(1)
295
296
297
298flatpak                                                         FLATPAK RUN(1)
Impressum