1FLATPAK RUN(1) flatpak run FLATPAK RUN(1)
2
3
4
6 flatpak-run - Run an application or open a shell in a runtime
7
9 flatpak run [OPTION...] REF [ARG...]
10
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 flatpak creates a sandboxed environment for the application to run in
20 by mounting the right runtime at /usr and a writable directory at /var,
21 whose content is preserved between application runs. The application
22 itself is mounted at /app.
23
24 The details of the sandboxed environment are controlled by the
25 application metadata and various options like --share and --socket that
26 are passed to the run command: Access is allowed if it was requested
27 either in the application metadata file or with an option and the user
28 hasn't overridden it.
29
30 The remaining arguments are passed to the command that gets run in the
31 sandboxed environment. See the --file-forwarding for handling of file
32 arguments.
33
35 The following options are understood:
36
37 -h, --help
38 Show help options and exit.
39
40 -v, --verbose
41 Print debug information during command processing.
42
43 --ostree-verbose
44 Print OSTree debug information during command processing.
45
46 --arch=ARCH
47 The architecture to install for.
48
49 --command=COMMAND
50 The command to run instead of the one listed in the application
51 metadata.
52
53 --branch=BRANCH
54 The branch to use.
55
56 -d, --devel
57 Use the devel runtime that is specified in the application metadata
58 instead of the regular runtime, and use a seccomp profile that is
59 less likely to break development tools.
60
61 --runtime=RUNTIME
62 Use this runtime instead of the one that is specified in the
63 application metadata. This is a full tuple, like for example
64 org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
65 empty or missing parts are filled in with the corresponding values
66 specified by the app.
67
68 --runtime-version=VERSION
69 Use this version of the runtime instead of the one that is
70 specified in the application metadata. This overrides any version
71 specified with the --runtime option.
72
73 --share=SUBSYSTEM
74 Share a subsystem with the host session. This overrides the Context
75 section from the application metadata. SUBSYSTEM must be one of:
76 network, ipc. This option can be used multiple times.
77
78 --unshare=SUBSYSTEM
79 Don't share a subsystem with the host session. This overrides the
80 Context section from the application metadata. SUBSYSTEM must be
81 one of: network, ipc. This option can be used multiple times.
82
83 --socket=SOCKET
84 Expose a well known socket to the application. This overrides to
85 the Context section from the application metadata. SOCKET must be
86 one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
87 session-bus, ssh-auth. This option can be used multiple times.
88
89 --nosocket=SOCKET
90 Don't expose a well known socket to the application. This overrides
91 to the Context section from the application metadata. SOCKET must
92 be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
93 session-bus, ssh-auth. This option can be used multiple times.
94
95 --device=DEVICE
96 Expose a device to the application. This overrides to the Context
97 section from the application metadata. DEVICE must be one of: dri,
98 kvm, all. This option can be used multiple times.
99
100 --nodevice=DEVICE
101 Don't expose a device to the application. This overrides to the
102 Context section from the application metadata. DEVICE must be one
103 of: dri, kvm, all. This option can be used multiple times.
104
105 --allow=FEATURE
106 Allow access to a specific feature. This overrides to the Context
107 section from the application metadata. FEATURE must be one of:
108 devel, multiarch, bluetooth. This option can be used multiple
109 times.
110
111 See flatpak-build-finish(1) for the meaning of the various
112 features.
113
114 --disallow=FEATURE
115 Disallow access to a specific feature. This overrides to the
116 Context section from the application metadata. FEATURE must be one
117 of: devel, multiarch, bluetooth. This option can be used multiple
118 times.
119
120 --filesystem=FS
121 Allow the application access to a subset of the filesystem. This
122 overrides to the Context section from the application metadata. FS
123 can be one of: home, host, xdg-desktop, xdg-documents,
124 xdg-download, xdg-music, xdg-pictures, xdg-public-share,
125 xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache,
126 xdg-data, an absolute path, or a homedir-relative path like ~/dir
127 or paths relative to the xdg dirs, like xdg-download/subdir. The
128 optional :ro suffix indicates that the location will be read-only.
129 The optional :create suffix indicates that the location will be
130 read-write and created if it doesn't exist. This option can be used
131 multiple times.
132
133 --nofilesystem=FILESYSTEM
134 Remove access to the specified subset of the filesystem from the
135 application. This overrides to the Context section from the
136 application metadata. FILESYSTEM can be one of: home, host,
137 xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures,
138 xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a
139 homedir-relative path like ~/dir. This option can be used multiple
140 times.
141
142 --add-policy=SUBSYSTEM.KEY=VALUE
143 Add generic policy option. For example,
144 "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
145 map to this metadata:
146
147 [Policy subsystem]
148 key=v1;v2;
149
150
151 This option can be used multiple times.
152
153 --remove-policy=SUBSYSTEM.KEY=VALUE
154 Remove generic policy option. This option can be used multiple
155 times.
156
157 --env=VAR=VALUE
158 Set an environment variable in the application. This overrides to
159 the Context section from the application metadata. This option can
160 be used multiple times.
161
162 --own-name=NAME
163 Allow the application to own the well known name NAME on the
164 session bus. If NAME ends with .*, it allows the application to own
165 all matching names. This overrides to the Context section from the
166 application metadata. This option can be used multiple times.
167
168 --talk-name=NAME
169 Allow the application to talk to the well known name NAME on the
170 session bus. If NAME ends with .*, it allows the application to
171 talk to all matching names. This overrides to the Context section
172 from the application metadata. This option can be used multiple
173 times.
174
175 --system-own-name=NAME
176 Allow the application to own the well known name NAME on the system
177 bus. If NAME ends with .*, it allows the application to own all
178 matching names. This overrides to the Context section from the
179 application metadata. This option can be used multiple times.
180
181 --system-talk-name=NAME
182 Allow the application to talk to the well known name NAME on the
183 system bus. If NAME ends with .*, it allows the application to talk
184 to all matching names. This overrides to the Context section from
185 the application metadata. This option can be used multiple times.
186
187 --persist=FILENAME
188 If the application doesn't have access to the real homedir, make
189 the (homedir-relative) path FILENAME a bind mount to the
190 corresponding path in the per-application directory, allowing that
191 location to be used for persistent data. This overrides to the
192 Context section from the application metadata. This option can be
193 used multiple times.
194
195 --log-session-bus
196 Log session bus traffic. This can be useful to see what access you
197 need to allow in your D-Bus policy.
198
199 --log-system-bus
200 Log system bus traffic. This can be useful to see what access you
201 need to allow in your D-Bus policy.
202
203 -p, --die-with-parent
204 Kill the entire sandbox when the launching process dies.
205
206 --file-forwarding
207 If this option is specified, the remaining arguments are scanned,
208 and all arguments that are enclosed between a pair of '@@'
209 arguments are interpreted as file paths, exported in the document
210 store, and passed to the command in the form of the resulting
211 document path. Arguments between '@@u' and '@@' are considered
212 uris, and any file: uris are exported. The exports are
213 non-persistent and with read and write permissions for the
214 application.
215
217 $ flatpak run org.gnome.GEdit
218
219 $ flatpak run --devel --command=bash org.gnome.Builder
220
221 $ flatpak run --command=bash org.gnome.Sdk
222
224 flatpak(1), flatpak-override(1), flatpak-enter(1)
225
226
227
228flatpak FLATPAK RUN(1)