flatpak/doc/flatpak-spawn.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<refentry id="flatpak-spawn">

    <refentryinfo>
        <title>flatpak spawn</title>
        <productname>flatpak</productname>

        <authorgroup>
            <author>
                <contrib>Developer</contrib>
                <firstname>Alexander</firstname>
                <surname>Larsson</surname>
                <email>alexl@redhat.com</email>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>flatpak spawn</refentrytitle>
        <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
        <refname>flatpak-spawn</refname>
        <refpurpose>Run commands in a sandbox</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
            <cmdsynopsis>
                <command>flatpak-spawn</command>
                <arg choice="opt" rep="repeat">OPTION</arg>
                <arg choice="plain">COMMAND</arg>
                <arg choice="opt" rep="repeat">ARGUMENT</arg>
            </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
        <title>Description</title>

        <para>
            Unlike other flatpak commands, <command>flatpak-spawn</command> is available
            to applications inside the sandbox. It runs <arg choice="plain">COMMAND</arg>
            outside the sandbox: either in another sandbox, or on the host.
        </para>

        <para>
            When called without <option>--host</option>, <command>flatpak-spawn</command>
            uses the Flatpak portal to create a copy of the sandbox it was called from,
            optionally using tighter permissions and optionally the latest version of the
            app and runtime (see <option>--latest-version</option>).
        </para>

    </refsect1>

    <refsect1>
        <title>Options</title>

        <para>The following options are understood:</para>

        <variablelist>
            <varlistentry>
                <term><option>-h</option></term>
                <term><option>--help</option></term>

                <listitem><para>
                    Show help options and exit.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-v</option></term>
                <term><option>--verbose</option></term>

                <listitem><para>
                    Print debug information
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--forward-fd=FD</option></term>

                <listitem><para>
                    Forward a file descriptor
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--clear-env</option></term>

                <listitem><para>
                    Run with a clean environment
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--watch-bus</option></term>

                <listitem><para>
                    Make the spawned command exit if the caller disappears from the session bus
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--env=VAR=VALUE</option></term>

                <listitem><para>
                    Set an environment variable
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--latest-version</option></term>

                <listitem><para>
                  Use the latest version of the refs that are used to set up the sandbox
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--no-network</option></term>

                <listitem><para>
                    Run without network access
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox</option></term>

                <listitem><para>
                  Run fully sandboxed. See the documentation for the <option>--sandbox</option>
                  option in <citerefentry><refentrytitle>flatpak-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                </para><para>
                  See the <option>--sandbox-expose</option> and
                  <option>--sandbox-expose-ro</option> options for selective file access.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox-expose=NAME</option></term>

                <listitem><para>
                  Expose read-write access to a file in the sandbox.
                </para><para>
                  Note that absolute paths or subdirectories are not allowed.
                  The files must be in the <filename>sandbox</filename> subdirectory of
                  the instance directory (i.e. <filename>~/.var/app/$APP_ID/sandbox</filename>).
                <para></para>
                  This option is useful in combination with <option>--sandbox</option> (otherwise the
                  instance directory is accessible anyway).
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox-expose-ro=NAME</option></term>

                <listitem><para>
                  Expose readonly access to a file in the sandbox.
                </para><para>
                  Note that absolute paths or subdirectories are not allowed.
                  The files must be in the <filename>sandbox</filename> subdirectory of
                  the instance directory (i.e. <filename>~/.var/app/$APP_ID/sandbox</filename>).
                <para></para>
                  This option is useful in combination with <option>--sandbox</option> (otherwise the
                  instance directory is accessible anyway).
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--host</option></term>

                <listitem><para>
                  Run the command unsandboxed on the host. This requires access to
                  the org.freedesktop.Flatpak D-Bus interface.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--directory=DIR</option></term>

                <listitem><para>
                  The working directory in which to run the command.
                </para><para>
                  Note that the given directory must exist in the sandbox or, when used in conjunction
                  with <option>--host</option>, on the host.
                </para></listitem>
            </varlistentry>

        </variablelist>
    </refsect1>

    <refsect1>
        <title>Examples</title>

        <para>
            <command>$ flatpak-spawn ls /var/run</command>
        </para>

    </refsect1>

    <refsect1>
        <title>See also</title>

        <para>
            <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>
        </para>

    </refsect1>

</refentry>