Command-line tools and web UIs
Some packages have no window of their own. A command-line tool (FFmpeg,
yt-dlp, 7-Zip) is typed at in a terminal. A local server (llama.cpp,
stable-diffusion.cpp) runs in a terminal and is used through the page it
serves in the browser. Both launch from a .desktop with Terminal=true, and
both say which they are in flatpark.yml:
catalog:
interface: cli # a command-line tool: the site shows "CLI"
# interface: web # a local server used in the browser: the site shows "Web UI"
Leaving the field out means gui, an app with a window. The descriptor audit
fails a Terminal=true launcher that is left at gui, and cli without
Terminal=true. A server with only an API and no page, like ollama serve, is
cli.
For agents
Files are passed by path, so grant home
A GUI app gets the user’s files through the file-chooser portal and needs no grant. A command-line tool gets them as paths in its arguments, and the sandbox sees only the directories the package grants. Outside them, things go wrong without any error:
- The working directory disappears. When the shell’s current directory is
not visible in the sandbox,
flatpak runstarts the tool in the sandbox’s own empty$HOME.ffmpeg -i in.mp4 out.mkvrun from~/Videoswith onlyxdg-downloadgranted can’t findin.mp4. - Output is lost. A relative output path, or a tool that writes to the
current directory by default (yt-dlp, gallery-dl), writes into that empty
$HOME, which is a tmpfs. The command reports success and the file is gone when it exits.
A narrow grant (xdg-download, xdg-pictures) only works if users cd there
first, and a tool whose job is processing whatever file the user names has no
single right directory. Grant --filesystem=home, declare it under
policy.dangerous_permissions with one line on why, and say in the metainfo
what is not covered:
policy:
dangerous_permissions:
# A command-line tool takes files as paths in its arguments; there is no
# file chooser, and a working directory outside the grant is silently
# replaced by the sandbox's empty home.
- --filesystem=home
- What home doesn’t cover:
/tmpinside the sandbox is private, and external drives (/run/media,/mnt) are not in home. Give the override for them in the metainfo:flatpak override --user --filesystem=/run/media <id>. --persiststops working once home is granted. A tool’s dotdir (~/.android) is then read from the real home, shared with a native install. That is usually what the user wants; drop the--persistline.- A tool that touches no user files (a system monitor, a model server whose models live in its own storage) gets no file grant at all.
--file-forwardingis not a substitute.flatpak run --file-forwarding <id> @@ in.mp4 @@exports existing files through the document portal, but can’t create an output file and isn’t something users type.
Standard input and output, pipes and exit codes pass through flatpak run
unchanged, and so does the terminal, so interactive tools and TUIs work.
The launcher
Exec= in a terminal launcher should leave the user somewhere usable. For a
tool that takes arguments, open a shell in the home directory with a two-line
banner saying which commands it has and how to close it, as
FFmpeg does. The tool’s
binary on PATH inside the sandbox is then the command the user types.
From the user’s own terminal the command is flatpak run <id>, and each extra
binary is flatpak run --command=<name> <id>. Put both in the metainfo
description; the app page shows them. Mark the .desktop ConsoleOnly in
Categories so menus that hide terminal programs can.
Local servers used in the browser (interface: web)
- Bind to loopback. Start the server with
--host 127.0.0.1, so the API isn’t open to the network, and put the address in the.desktopCommentand the metainfo. - Open the page if the server can. Use the server’s own option
(
speech serve --open) rather than a wrapper that guesses when it is ready. Otherwise the metainfo tells the user which address to open and that the terminal must stay open. Ctrl+C stops it. - Editions get their own port. CPU, CUDA and Vulkan editions installed side by side each default to a different port and keep separate model stores.
- Files go through the page. The browser uploads and downloads them, so the server needs no home grant. Model directories on the host are an optional read-only override in the metainfo.
Examples: llama.cpp, speech.cpp.