FLATPAK-REMOTE(5)

💖 FLATPAK-REMOTE — the remote config glow-up guide 💖

okay bestie, so this is the flatpak-remote manual page, section 5 (file formats, the ✨fancy✨ corner of the man universe), and we're gonna talk about how Flatpak keeps track of your remotes. no cap. 🎀

---

🌈 NAME 🌈

flatpak-remote — Configuration for a remote 🦋

---

✨ DESCRIPTION ✨

so Flatpak stores all the info about your configured remotes for an installation location in $installation/repo/config. like, that's the spot. 📍

• for the default system-wide installation, the remotes live in $prefix/var/lib/flatpak/repo/config
• for the per-user installation, they live in $HOME/.local/share/flatpak/repo/config

ngl, normally you do not need to edit remote config files by hand — that's giving "why would you do that to yourself" energy. the flatpak remote-modify command is the one you should be using to change properties of remotes. use it. love it. 💅

also, system-wide remotes can be statically preconfigured by dropping flatpakrepo(5) files into /usr/share/flatpak/remotes.d/ and /etc/flatpak/remotes.d/. and if a file with the same name exists in both places, the file under /etc takes precedence — like, /etc is the main character, /usr is the understudy. 👑

---

📁 FILE FORMAT 📁

the remote config file format uses the exact same .ini file format that systemd unit files or application .desktop files use. so if you've met one, you've met them all, fr fr. 🫶

🌸 [remote ...] 🌸

all the configuration for the remote with name NAME is contained in the [remote "NAME"] group. that's the whole vibe. ✨

the following keys are recognized by OSTree, among others:

• url (string) — the url for the remote. an URL of the form oci+https:// or oci+http:// is a Flatpak extension that indicates the remote is not an ostree repository, but is rather an URL to an index of OCI images that are stored within a container image registry. 🐳

for OCI remotes, client and CA certificates are read from /etc/containers/certs.d and ~/.config/containers/certs.d as documented in containers-certs.d(5).

• gpg-verify (boolean) — whether to use GPG verification for content from this remote. 🔐
• gpg-verify-summary (boolean) — whether to use GPG verification for the summary of this remote.

⚠️ this is ignored if collection-id is set, because refs are verified in commit metadata in that case. and heads up: enabling gpg-verify-summary would break peer to peer distribution of refs. so like… don't. 💀

• collection-id (string) — the globally unique identifier for the upstream collection repository, to allow mirrors to be grouped. 🪞

all flatpak-specific keys have a xa. prefix, because branding, obviously:

• xa.disable (boolean) — whether the remote is disabled. defaults to false.
• xa.prio (integer) — the priority for the remote. this is used when listing remotes, and when searching them for the runtime needed by an app. the remote providing the app is searched for its runtime before others with equal priority. defaults to 1.
• xa.noenumerate (boolean) — whether this remote should be ignored when presenting available apps/runtimes, or when searching for a runtime dependency. defaults to false.
• xa.nodeps (boolean) — whether this remote should be excluded when searching for dependencies. defaults to false.
• xa.title (string) — an optional title to use when presenting this remote in a UI. ✨
• xa.title-is-set (boolean) — this key is set to true if xa.title has been explicitly set.
• xa.comment (string) — an optional single-line comment to use when presenting this remote in a UI. 💬
• xa.comment-is-set (boolean) — this key is set to true if xa.comment has been explicitly set.
• xa.description (string) — an optional full-paragraph of text to use when presenting this remote in a UI. 📝
• xa.description-is-set (boolean) — this key is set to true if xa.description has been explicitly set.
• xa.homepage (string) — an optional URL that points to a website for this repository to use when presenting this remote in a UI. 🌐
• xa.homepage-is-set (boolean) — this key is set to true if xa.homepage has been explicitly set.
• xa.icon (string) — an optional URL that points to an icon for this repository to use when presenting this remote in a UI. 🎀
• xa.icon-is-set (boolean) — this key is set to true if xa.icon has been explicitly set.
• xa.default-branch (string) — the default branch to use when installing from this remote. 🌿
• xa.default-branch-is-set (boolean) — this key is set to true if xa.default-branch has been explicitly set.
• xa.main-ref (string) — the main reference served by this remote. this is used for origin remotes of applications installed via a flatpakref file. 🎯
• xa.signature-lookaside (string) — URL to load signatures from (OCI remotes only), using the containers/image separate storage mechanism.[1]

---

🔥 EXAMPLES 🔥

here's what it actually looks like, bestie — icons only, no edits:

[remote "gnome-nightly-apps"]
gpg-verify=true
gpg-verify-summary=true
url=https://sdk.gnome.org/nightly/repo-apps/
xa.title=GNOME Applications

[remote "flathub"]
gpg-verify=true
gpg-verify-summary=false
collection-id=org.flathub.Stable
url=https://dl.flathub.org/repo/
xa.title=Flathub

---

👀 SEE ALSO 👀

• flatpak-remote-modify(1)

---

🗒️ NOTES 🗒️

1. containers/image separate storage mechanism. https://github.com/containers/image/blob/main/docs/signature-protocols.md

---

and that's the whole page, periodt. 💖 this came to you from the flatpak crew, filed under FLATPAK REMOTE(5) — go forth and configure your remotes responsibly, you absolute icon. 🦋🌸💅