Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Flatpak bundle

From ReverseEngineering.wiki
Format
Extensions .flatpak, .flatpakref
License LGPL-2.1 (flatpak)
On this wiki Facts · Code · Notes · Topics

A single-file .flatpak bundle is a GVariant of the OSTree static-delta superblock type (no magic number) whose metadata dictionary names the ref, origin, app metadata and optional GPG keys and icons; installed apps live in an OSTree repository with a deploy directory holding a metadata keyfile.

Two forms

  1. Repository: apps are pulled into an OSTree repository (objects store, content-addressed files) and checked out ("deployed") into a deploy directory that contains a metadata keyfile and the files/ tree. flatpak-dir.c reads deploy_dir/metadata in several places (for example line 3864).
  2. Single-file bundle (.flatpak): created for offline distribution. There is no file magic: flatpak_bundle_load (common/flatpak-repo-utils.c, lines 3681-3815) maps the whole file and calls g_variant_new_from_bytes with the type OSTREE_STATIC_DELTA_SUPERBLOCK_FORMAT, i.e. the file is one serialized GVariant of OSTree's static delta superblock type.

Bundle layout as flatpak reads it

Child 3 of the superblock is the checksum of the target commit (32 bytes, to_csum_v, validated with ostree_validate_structureof_csum_v). Child 0 is a string-keyed dictionary (a{sv}) with these keys, all looked up in flatpak_bundle_load:

Key Type Meaning
ostree.endianness byte l (little) or B (big): byte order of the GVariant data, swapped if it differs from the host
ref string the full ref, for example app/org.example.App/x86_64/stable; required ("Invalid bundle, no ref in metadata")
origin string URL of the originating repository
runtime-repo string repository to fetch the runtime from
collection-id string OSTree collection id (empty means none)
metadata string the application's metadata keyfile text
gpg-keys byte array embedded GPG keys

In common/flatpak-bundle-ref.c (lines 333-341) the dictionary also supplies appdata (AppStream, byte string), icon-64 and icon-128 (byte strings).

For the analyst

  • Recognition is structural: a .flatpak is not ELF, not a tar, and has no magic bytes. Unverified: the GVariant type string is believed to be (a{sv}tayay...); take the type from OSTree's source before parsing by hand.
  • Easiest route: flatpak build-bundle output is read by ostree tooling and by flatpak itself; Unverified: flatpak install --bundle followed by browsing the deploy directory under the flatpak data directory reaches files/bin.
  • The program binaries are ELF files under files/ (the app) and in separate runtime deployments (shared libraries). Unverified: files/ as the root of the app tree.

See Technique:Identifying Linux and macOS package containers.

Sources

flatpak/flatpak (LGPL-2.1) at commit ed564f7cce: common/flatpak-repo-utils.c, common/flatpak-bundle-ref.c, common/flatpak-dir.c, read.

Code & repositories

  • https://github.com/flatpak/flatpak @ ed564f7cce7e6f81926fc4a2d58125a4adf64649 · license: LGPL-2.1-or-later (declared by the contributor; GitHub's detector did not recognize COPYING)
    Flatpak: common/flatpak-repo-utils.c flatpak_bundle_load, flatpak-bundle-ref.c
    Tested on: source read, not run · checked 2026-10-19