For the complete documentation index, see llms.txt. This page is also available as Markdown.

FlatImage

A hybrid of Flatpak sandboxing with AppImage portability

A FlatImage is closer to a container than to a single packaged application. It carries a whole subsystem, Alpine with apk or Arch with pacman, and its configuration lives in reserved space inside the ELF itself, so permissions, environment and bindings can be changed after the fact without rebuilding.

The payload is DwarFS, decompressed on the fly, and the tools to bring it up are statically linked and embedded.

The project moved from ruanformigoni/flatimage to its own flatimage organization. The old URL still redirects.


In soarpkgs

Soar installs this format from a repository, a URL, or a local file, and a recipe can name it as its type. No package in soarpkgs happens to use it at the moment.


Prerequisites (HOST)

  • Kernel user namespaces: the real requirement. The container is brought up unprivileged, so without them there is nothing to run in.

  • Fuse: used to mount the DwarFS payload. The tools are embedded, so there is nothing to install.

  • Fonts: required to display/render non-English characters, symbols and emoji.


Sandbox


Quirks

WARNINGS

  • NEVER run strip, objcopy or any other binary rewriting tool as they will often just strip the squashfs|dwarfs archive, only preserving the runtime.

  • A typical .flatimage file is not a real elf binary, thus will not survive this process.

  • An application that works in another format may still need a permission granted here before it does anything visible, since nothing is allowed until it is asked for.

Last updated