FlatFree

What is a Flatpak?

Flatpak is a next-generation application sandboxing and distribution system for Linux. It lets you package your application with all its dependencies so it runs the same way on every Linux distribution.

Prerequisites

Install the required tools:

# On Arch Linux
sudo pacman -S flatpak flatpak-builder

# On Fedora
sudo dnf install flatpak flatpak-builder

# On Ubuntu/Debian
sudo apt install flatpak flatpak-builder

Then add the Flathub runtime (required for building):

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub org.kde.Platform//6.10 org.kde.Sdk//6.10

Replace org.kde.Platform with your app's runtime (e.g., org.gnome.Platform for GNOME apps).

Step 1: Create a Manifest

A flatpak-builder manifest is a JSON or YAML file that describes your application. Here's a minimal example:

{
    "id": "org.example.MyApp",
    "runtime": "org.kde.Platform",
    "runtime-version": "6.10",
    "sdk": "org.kde.Sdk",
    "command": "myapp",
    "finish-args": [
        "--socket=wayland",
        "--socket=fallback-x11",
        "--share=ipc"
    ],
    "modules": [
        {
            "name": "myapp",
            "buildsystem": "cmake-ninja",
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/you/MyApp.git"
                }
            ]
        }
    ]
}

Key fields:

• id — Reverse-domain name (e.g., org.example.MyApp)
• runtime — Base runtime your app needs (org.kde.Platform, org.gnome.Platform, org.freedesktop.Platform)
• sdk — SDK matching your runtime (includes compilers and headers)
• command — The executable name that runs your app
• finish-args — Sandbox permissions your app needs
• modules — List of dependencies and your app, built in order

Step 2: Build Your Flatpak

Once you have a manifest, build it with:

flatpak-builder --force-clean build-dir org.example.MyApp.json

This downloads the runtime, builds all modules, and creates a build directory.

Step 3: Test It

Run your app from the build directory:

flatpak-builder --run build-dir org.example.MyApp.json myapp

Or install it locally to test:

flatpak-builder --install --user --force-clean build-dir org.example.MyApp.json
flatpak run org.example.MyApp

Step 4: Export to a Repository

Create a local ostree repo and export your build:

ostree init --repo=my-repo --mode=archive-z2
flatpak build-export my-repo build-dir
flatpak build-update-repo my-repo

Install from your local repo to verify:

flatpak remote-add --no-gpg-verify my-repo my-repo --from=oci://my-repo
flatpak install my-repo org.example.MyApp

Step 5: Submit to FlatFree

Use our CLI tool or manual process:

# Using the CLI tool
curl -L https://github.com/spivanatalie64/FlatFree/releases/download/v1.0.0/flatfree-submit -o flatfree-submit
chmod +x flatfree-submit
./flatfree-submit org.example.MyApp.json

Or manually:

1. Fork github.com/spivanatalie64/FlatFree
2. Create a directory named org.example.MyApp/
3. Add your manifest file inside it
4. Open a pull request — our CI validates and merges automatically

Common Finish-Args

--socket=wayland	Wayland display server
--socket=fallback-x11	X11 fallback
--share=ipc	Shared memory (needed for X11)
--share=network	Network access
--device=dri	OpenGL / GPU acceleration
--filesystem=host	Access host filesystem
--talk-name=org.freedesktop.Notifications	DBus notifications
--system-talk-name=org.freedesktop.UDisks2	System DBus (disk access)

Need Help?

Open an issue on GitHub or read the official Flatpak Builder documentation.