What is AetherPak?#

1. What AetherPak Is#

AetherPak is an umbrella project that provides tooling and automation for building Flatpak applications and hosting them as fully functional, publicly installable Flatpak repositories — all using simple static hosting and OCI-compatible container registries. 1

The core of AetherPak is the CLI tool, which exposes the full Flatpak build and distribution pipeline as composable, scriptable commands. Around this, AetherPak provides a set of complementary tools — including GitHub Actions workflows, container images, and reference examples — that make the process as effortless as possible.

Put simply: point AetherPak at your existing Flatpak manifest, and it produces a working app repository — complete with a landing page, one-click install support, and optional cryptographic signing. No servers to provision. No infrastructure to maintain. 2

The intention is to give application builders everything they need to distribute their Flatpaks on their own managed repositories without complicated infrastructure — just any static page host (e.g., GitHub Pages, Cloudflare, GitLab Pages) and a container registry that supports anonymous access and OCI (e.g., quay.io, ghcr.io, etc.). The high-level processes remain the same no matter where the repository is hosted and where the Flatpak blobs are served from.

A typical deployment splits hosting across two simple tiers:

• An OCI-compatible container registry (like GitHub Container Registry, Quay.io, or Docker Hub) stores your compiled application layers as OCI images — the large blobs that Flatpak clients download when installing or updating your app.
• A static web host (like GitHub Pages, GitLab Pages, or Cloudflare Pages) serves a lightweight JSON repository index, a landing page, a .flatpakrepo remote-configuration file, and per-app .flatpakref installation files.

This combination gives you the best of both worlds: CDN-backed, large-chunk binary distribution from the container registry, and a feather-light metadata layer from the static host. The result is fast, scalable hosting with zero operational cost when using free tiers. 3

Whether you're a Flatpak packager who's never touched automation, or a CI/CD expert who's never built a Flatpak, AetherPak is designed to meet you where you are. For most users, the GitHub Actions integration provides a high-level reusable workflow that handles everything automatically. Advanced users can use the CLI directly to customize every step of the pipeline.

In short: AetherPak makes it easy for open-source Linux desktop application maintainers to build and host self-managed, distributed Flatpak repositories. 4

2. Why AetherPak Exists: The Problem It Solves#

The traditional barrier to Flatpak self-distribution#

Flatpak is an excellent packaging format for Linux desktop applications. But distributing a Flatpak app outside of Flathub has traditionally required running your own OSTree repository server — meaning you'd need to provision and maintain hosting infrastructure just to give users a way to install your software. For most independent developers and small teams, that's a meaningful barrier.

Even if you were already using GitHub to host your code, the natural instinct to serve the OSTree repository from GitHub Pages quickly runs into a hard wall: a static OSTree repository is made up of hundreds of tiny objects. Every install or update requires the client to make hundreds of individual HTTP requests to fetch all those objects. That's slow for your users, and it rapidly exhausts GitHub Pages' per-hour rate limits. 5

"A static-HTTP OSTree repository serves an app as many small objects, so clients make hundreds of requests. That is slow, and it trips GitHub Pages rate limits." 5

The result was an uncomfortable choice: pay for and operate your own server, squeeze yourself into Flathub's submission and review process, or simply not distribute a Flatpak at all.

The AetherPak solution#

AetherPak solves this by using Flatpak's native OCI support instead of traditional OSTree HTTP. 6 Rather than serving hundreds of small files, application layers are packaged as OCI images and stored in a container registry — where they're served as large, efficiently chunked blobs with CDN backing. The only thing the static host needs to serve is a small JSON index file and a handful of human-readable configuration files.

"Serving a static OSTree repository from a simple web server or static host involves transferring hundreds of small, separate file objects. This results in slow client-side installations and trips provider request limits. AetherPak addresses this with a flexible, hybrid OCI-static hosting model." 7

The practical upshot: the entire distribution pipeline — building, signing, publishing, and serving — can run on freely available infrastructure. No servers. No rate-limit headaches. No infrastructure bill. 8

Eliminating the gatekeeper problem#

There's a broader problem too. Centralized distribution platforms like Flathub are tremendously useful, but they also create a single point of control. Your app needs to meet their policies, pass their review process, and operate on their timeline. For many legitimate projects — apps that are too niche, too specialized, or simply don't fit the submission criteria — that centralized model is a closed door.

AetherPak takes a different philosophical stance: every maintainer should be able to own their own distribution channel, with no external gatekeepers and no submission queues. We'll explore that philosophy in more depth in Embracing Distributed Ownership.

3. Who AetherPak Serves#

AetherPak is built for anyone who wants to distribute Flatpak applications without ceding control to a centralized platform or operating their own infrastructure. In practice, that includes a wide range of users:

Open-source developers and independent maintainers who want to ship Flatpak apps on their own terms — controlling their own release cadence, signing keys, and landing page — without waiting on a third-party review queue.

Small teams without infrastructure resources. If you're a small project that doesn't have the engineering bandwidth to provision and maintain a server, AetherPak gives you a production-quality distribution pipeline using freely available infrastructure.

Projects outside Flathub's scope. Flathub has specific submission criteria and policies. Projects that don't qualify — whether due to licensing, scope, audience, or policy — can still offer their users a first-class Flatpak experience through AetherPak.

Internal and enterprise distribution. Organizations that want to distribute internal tools as Flatpak apps to their Linux desktops can use AetherPak with private repositories and container registries without exposing anything publicly.

Developers who want full pipeline control. Because AetherPak exposes the full pipeline as composable CLI commands (modeled on Git's plumbing/porcelain philosophy), advanced users can customize every step: insert their own validation, drive dynamic build matrices, or integrate with existing CI systems. 9

Maintainers who care about autonomy and decentralization. If you believe that app distribution infrastructure should be something every developer can own — not a privilege granted by a platform — AetherPak is built for you.

For a concrete example of what all this looks like in practice, see the actions-demo repository, which builds GNOME Sudoku for both x86_64 and aarch64 from a roughly 20-line workflow file and deploys a live, installable Flatpak repository at aetherpak.github.io/actions-demo. 10

4. Embracing Distributed Ownership Over Centralized App Stores#

The centralized model and its limits#

Most Linux app distribution today funnels through centralized platforms: Flathub for Flatpaks, the Snap Store for snaps, and so on. These platforms offer real value — discoverability, unified review, and a trusted source for end users. But they also carry an implicit cost: a single organization controls who can publish, what policies apply, how quickly submissions are reviewed, and whether your app stays available.

For many developers, this is an acceptable trade-off. But for others — projects that don't fit submission criteria, developers who need to move faster than a review queue allows, or teams distributing internal tools — it's a constraint that blocks legitimate use cases entirely.

Every maintainer owns their own distribution channel#

AetherPak takes a fundamentally different approach: every repository becomes its own self-contained app store.

When you deploy with AetherPak, you own everything:

• Your signing keys. You generate them, you rotate them, you control who has access.
• Your release cadence. Push to your main branch and your app is published. No waiting for external approval.
• Your landing page. The generated site is yours to customize — from templates to full HTML/CSS control.
• Your entire pipeline. From the build container to the registry to the hosting, every component is either in your repository or a declared dependency you can pin and audit.

No gatekeeper. No submission queue. No external policy that can change under you overnight. 4

The Git analogy#

Think about how version control works today. You don't need anyone's permission to host a Git repository. GitHub, GitLab, Codeberg, or your own server — you pick the infrastructure, and the protocol is open. The decentralization of code hosting is something the developer community takes for granted.

AetherPak applies the same idea to app distribution. Just as anyone can host a Git repository, anyone with a GitHub account can now host a Flatpak repository. You own your repo; you own your releases.

This isn't just a technical convenience — it's a design philosophy. The plumbing/porcelain architecture of the AetherPak CLI is explicitly modeled on Git for the same reason: composable, auditable, and free from magic black boxes. 11 The same spirit of transparency and control that makes Git trustworthy for source code applies to AetherPak's approach to app distribution.

Beyond GitHub#

While GitHub provides a convenient, free-tier solution for most users, AetherPak isn't locked to GitHub specifically. The architecture is intentionally generic and platform-agnostic:

• The static control plane (JSON index, .flatpakrepo, .flatpakref) can be hosted on GitHub Pages, GitLab Pages, Netlify, Cloudflare Pages, S3, or any static web host. 12
• The OCI data plane (application layers) can live in GHCR, Docker Hub, Quay.io, or any OCI-compliant registry. 13

The high-level processes remain the same no matter where the repository is hosted and where the Flatpak blobs are served from. The use of GitHub's free tier is the recommended path for most users, but the underlying design is about democratizing the infrastructure for Flatpak distribution — not about creating dependency on any single vendor.

5. The AetherPak Ecosystem: Components and Repositories#

AetherPak is a family of repositories that work together. Here's a quick map of each component and its role.

aetherpak/actions — The GitHub Actions Integration#

A GitHub Actions integration that provides both a high-level reusable workflow (publish.yml) and a set of modular composite actions you can use individually. 14 This is one tool in the AetherPak toolbox, focused specifically on automating the pipeline within GitHub Actions.

The reusable workflow orchestrates the complete pipeline in five sequential stages:

15

For most maintainers, the reusable workflow is everything they need. The composite actions are there when you need to build a custom pipeline or insert your own steps.

aetherpak/cli — The Command-Line Tool#

A standalone Go CLI that exposes the full AetherPak pipeline as composable, scriptable commands. 16 Designed to work in any environment — GitHub Actions runners, local workstations, or custom CI systems.

The CLI follows a plumbing/porcelain design philosophy modeled directly on Git: 11

• Plumbing commands (e.g., build, push-oci, build-site, plan) are independent, single-responsibility primitives suited for complex workflows and custom CI matrices.
• Porcelain commands (e.g., publish, release) are high-level wrappers that coordinate multiple plumbing modules for the most common cases.

You can use publish for day-to-day work and drop down to individual commands whenever you need fine-grained control — for example, to insert validation between build and publish, or to drive a dynamic matrix from an external source. 9

For a full introduction to the CLI, see Getting Started with the AetherPak CLI.

aetherpak/setup-cli — The CLI Installer Action#

A lightweight GitHub Action that downloads and installs the aetherpak CLI binary on a runner. 17 All composite actions in aetherpak/actions call this automatically if the CLI isn't already on PATH, but you can invoke it directly to pin to a specific CLI version.

aetherpak/flatpak-containers — The Build Environment#

Two Fedora-based container images that provide a self-contained Flatpak toolchain: ghcr.io/aetherpak/flatpak (base) and ghcr.io/aetherpak/flatpak-builder (with build tools). 18

A key design goal is parity with the Flathub build environment — including the same version of flatpak-builder-lint used by Flathub's own CI. This means lint failures you see locally will be the same ones you'd see on Flathub, and builds produce consistent results regardless of where they run. 19

Both images are published for linux/amd64 and linux/arm64 as multi-arch manifests, enabling automatic architecture selection.

aetherpak/actions-demo — The Reference Deployment#

A minimal, fully working example that builds GNOME Sudoku (org.gnome.Sudoku) for x86_64 and aarch64 from a roughly 20-line workflow file, with GPG signing enabled. 20

• Live landing page: aetherpak.github.io/actions-demo
• Repository: aetherpak/actions-demo

If you're new to AetherPak, this is the best place to start. The demo shows exactly what a working deployment looks like, end to end.

aetherpak.github.io — The Project Website#

The project's public website and documentation landing page, which provides an overview of AetherPak's capabilities and links to the full documentation. 4

6. How the Architecture Works (High-Level Overview)#

AetherPak's design is built around a clean two-tier architecture that separates what needs to be fast and efficient (binary distribution) from what needs to be lightweight and discoverable (repository metadata). 21

The two tiers#

Tier 1 — OCI Container Registry: The Data Plane

This is where the actual application content lives. When AetherPak builds your Flatpak, it converts the compiled OSTree repository into an OCI image and pushes it to a container registry. Each app/arch/branch combination is stored as a separate image tag (e.g., org.gnome.Sudoku-stable-x86_64).

When a user installs your app, Flatpak pulls these OCI images directly from the registry — which means it downloads large, efficiently-chunked blobs over a CDN-backed connection. There are no hundreds of tiny requests, no rate limits to worry about, and no performance bottlenecks at the hosting layer.

Tier 2 — Static Web Host: The Control Plane

The static host serves only lightweight, human-readable content:

• index/static — a JSON index that Flatpak clients read to discover available apps and their current digest pointers
• index.html — a generated landing page with install instructions
• .flatpakrepo — a remote-configuration file users can add to register your repository with Flatpak
• Per-app .flatpakref files — one-click installation shortcuts

Because the static host is only serving small text files (not binary blobs), it stays well within rate limits regardless of how many users you have. 3

The end-to-end pipeline#

manifest ──build──▶ OSTree repo ──publish──▶ OCI image in GHCR
                                         └──▶ index/static + index.html on Pages

client: Pages index ──(digest)──▶ GHCR blobs

22

1. Build: flatpak-builder compiles your manifest inside a container to produce a local OSTree repository.
2. Publish OCI: the OSTree repo is converted to an OCI image and pushed to a container registry, tagged by (app-id, branch, arch).
3. Publish Site: the per-app record (including the registry digest) is merged into the shared index/static. The updated index, landing page, .flatpakrepo, and .flatpakref files are deployed to the static host.
4. Install (client side): the user's Flatpak client reads the index from the static host, looks up the current digest for the desired app and arch, and pulls the corresponding OCI image layers directly from the container registry.

Efficient, scalable, and platform-agnostic#

This architecture is deliberately designed to use simple, freely available infrastructure while delivering a production-quality distribution experience:

• Free for public repositories: Container registries like GHCR and static hosts like GitHub Pages are both free for public repos.
• Scalable by default: Container registries are CDN-backed and handle concurrent downloads without any special configuration.
• Platform-agnostic: AetherPak works with any OCI-compliant registry and any static web host — the high-level processes remain the same regardless of provider.
• AppStream integration: the pipeline generates full AppStream metadata so your app is discoverable in Linux software catalogs like GNOME Software and KDE Discover — the same discovery tooling used by Flathub. 23

For a deeper technical dive into the pipeline, index format, OCI signing, and multi-app orchestration, see the ARCHITECTURE.md in the aetherpak/actions repository. 24