# flatpak

Flatpak applications on the two workstations (novox/hq research 027/02: "`snapd` and `flatpak` are
modules, on the two workstations only"; to-be 42 phase 2 step 9).

## Owns

| what | where |
|---|---|
| flatpak | package `flatpak` (official repositories) |

**The Flathub remote comes with the package.** The package ships `flathub.flatpakrepo` in
`/usr/share/flatpak/remotes.d`, and flatpak adds every file there to the system installation as a
remote. The module therefore declares no remote file of its own. `flatpak_remotes` checks that the
system installation has Flathub, and says so when it does not.

The installed applications and runtimes, and their data, are the operator's: found (ADR 0182).

## Improves

- **The laptop gains flatpak**, which only the desktop had, with Flathub.
- **Unused runtimes become visible and removable.** On the desktop on 2026-10-04, `/var/lib/flatpak`
  held 5.1 GB for three applications. They are Nextcloud on KDE 6.7, Warehouse on GNOME 46, and Plex on
  Freedesktop 23.08. Beside them sat the whole Freedesktop 22.08 platform, both of its GL extensions,
  and older codec and style extensions that nothing uses. `flatpak_unused` lists them read-only;
  `flatpak_remove_unused` lets flatpak remove them.
- **A duplicate remote is named.** The desktop has Flathub configured twice, once in the system
  installation and once in the account's, which has nothing installed from it. `flatpak_remotes`
  reports it.

## Tools

All answer JSON; `(r)` reads, `(a)` acts. Reads run as the operator account. An act on the system
installation (the default) goes through `sudo -n`; one on the account's own installation does not.

| tool | what |
|---|---|
| `flatpak_list` (r) | applications: id, name, version, branch, origin, installation, size in bytes |
| `flatpak_runtimes` (r) | runtimes and extensions, the same way |
| `flatpak_remotes` (r) | both installations' remotes, how many refs come from each, findings |
| `flatpak_updates` (r) | refs with a newer commit on their remote (needs the network) |
| `flatpak_unused` (r) | runtimes nothing needs, computed without changing anything (below), with the space each takes |
| `flatpak_disk_usage` (r) | each installation's directory on disk, and the 50 largest refs |
| `flatpak_install` (a) | install from a remote (default `flathub`) into the system or the account installation |
| `flatpak_remove` (a) | uninstall, keeping the application's data unless `delete_data` |
| `flatpak_update` (a) | update one ref, or everything in an installation |
| `flatpak_remove_unused` (a) | `uninstall --unused`: flatpak decides |
| `flatpak_job` (r) | a long act's state and the end of its output |

**Unused, computed.** `flatpak uninstall --unused` has no dry run: it asks, and answering *yes* removes.
So the read tool works it out from what flatpak already says. A runtime is in use when one of these
holds:

- an installed application names it as its runtime or SDK;
- it fills an extension point declared in the metadata of something in use, matched by id
  (subdirectories included) and accepted version;
- it is pinned.

The SDK is counted as used to err on the safe side. flatpak's own `--unused` may also remove an
application's SDK.

**Acts are jobs.** An install or update downloads hundreds of megabytes. Each act runs inside the
tool's process for up to 15 minutes, and is waited on for 18 s. A finished act is answered, and a
failed one as an error. One still running is answered with a job id for `flatpak_job`.

## What changes when it is assigned

- **laptop:** `flatpak` is installed, with Flathub as the system remote. Nothing else.
- **desktop:** nothing on disk; the package, installed by hand, becomes the mesh's.

## The one-off step for the operator (ADR 0182)

On the desktop, the account's own Flathub remote duplicates the system's and has nothing installed
from it. If it is not wanted: `flatpak remote-delete --user flathub`, once. The mesh did not make it,
so it does not remove it.

## Leaves as found

The applications and runtimes, the account installation under `~/.local/share/flatpak`, application
data under `~/.var/app`, and any remote other than the package's Flathub.