FlatImage

FlatImage is a hybrid of Flatpak sandboxing with AppImage portability, created by @ruanformigoni.

pkg_type: flatimage

Features

• Built-in sandboxing (permissions docs)
• Uses a base distro image (Alpine, CachyOS, etc.) as rootfs
• Modern desktop integration
• OCI image format

Naming Convention

FlatImage packages include the base image in the name:

firefox-alpine.flatimage        # Alpine base
steam-cachyos.flatimage         # CachyOS base
librewolf-alpine-nix.flatimage  # Alpine + Nix overlay

Prerequisites

• FUSE — required for mounting
• Fonts — for rendering non-Latin characters and emojis
• User Namespaces — required for sandboxing

Quirks

DANGER

• Never run strip, objcopy, or any binary rewriting tool on FlatImages. They will destroy the embedded squashfs|dwarfs archive, leaving only the runtime stub.
• A .flatimage file is not a real ELF binary.

Example SBUILD

#!/SBUILD
_disabled: false

pkg: "firefox-alpine"
pkg_id: "pkgforge-dev.firefox-alpine"
pkg_type: "flatimage"
ghcr_pkg: "pkgforge-dev/firefox-alpine"
app_id: "org.mozilla.firefox"
description: "Web browser (FlatImage)"
provides:
  - "firefox-alpine"
src_url:
  - "https://github.com/pkgforge-dev/firefox-flatimage"
x_exec:
  host:
    - "x86_64-linux"
    - "aarch64-linux"
  shell: "bash"
  pkgver: |
    curl -qfsSL "https://api.github.com/repos/pkgforge-dev/firefox-flatimage/releases/latest" | jq -r '.tag_name'
  run: |
    soar dl "https://github.com/pkgforge-dev/firefox-flatimage" --match "flatimage" -o "./${PKG}" --yes

See Also

• FlatImage documentation
• FlatImage GitHub