umbrel-apps is the package repository behind the Umbrel App Store

A catalogue of packages, one directory per app

This repository contains the app packages published in the official Umbrel App Store. Each top-level directory is an app package consumed by umbrelOS, and the store itself is browsable at apps.umbrel.com.

That sentence defines the whole thing, and it is worth being precise about what kind of repository this is. It is not an application, not a library and not a framework. It is a registry of packaging definitions, and the directory listing at the root is a catalogue: activepieces, actual, adguard-home, adventurelog, affine, agent-zero, agora, airtrail, akaunting, alby-nostr-wallet-connect, albyhub, am-i-exposed, anything-llm, appsmith, arcane, archivebox, audiobookshelf, autobrr and onward through the alphabet, with the listing truncated well before the end.

The primary language is recorded as Shell, which tells you something about the shape of a package. These are not application source trees. They are the bits needed to fetch, install, configure, update and expose an application that was built elsewhere.

The repository publishes no GitHub releases and carries no licence classification, and the last push was on 2026-10-22, so the catalogue is being updated continuously. For a user of the store, that continuity is the point: the store's contents are the state of this branch.

The App Store Standard is a browser-first rule, not a checklist

The README states one standard, and it is short enough to quote. Every app package should be understandable from the browser after install. It should open to a web UI, setup flow, login page, or status page that gives users a clear next step without SSH, CLI access, log scraping, or manual file edits.

The list of forbidden things is the interesting half. A package that is only usable by opening an SSH session does not qualify, and neither does one that makes a user read log files or edit configuration by hand to get through setup.

Beyond that, apps should feel natural on umbrelOS: sensible defaults, browser-based setup, predictable updates, and careful handling of user data. The README allows that some apps need special setup or expose advanced controls, but the default path should be clear from the browser.

That is a meaningful bar and a specific one. It rules out a large class of self-hosted software that assumes an operator with a terminal, and it pushes package authors towards applications that were already designed to be set up through a browser. It also means the work in a package is largely about presenting someone else's application well: defaults, first-run flow, update behaviour and data handling.

For a user, the standard is a promise they can rely on. Open the app, and something sensible happens.

Contribution is designed to be driven by a coding agent

The contributing section has an unusual instruction at the top, and it tells you how the project expects work to be done.

The easiest way to contribute is to send your coding agent to this repository and have it read AGENTS.md. That file helps the agent choose the right repo-local skill for the work, and the four kinds of work named are packaging an existing app, updating an App Store package, testing a package, and building a self-hosted app that can be packaged for the App Store.

The skills live in.agents/skills/ and are described as capturing the current Umbrel App Store guidance for app development, packaging and verification. There is also a.claude/ directory at the root, which is the same idea for a different agent tool, and a.tools/ directory for the repository's own tooling.

AGENTS.md at the root exists because the guidance is meant to be read by a machine rather than skimmed by a person. That is a coherent choice for a catalogue that changes daily and whose review burden is carried by automation, and it also means the rules are in the repository rather than in a wiki that a contributor may never find.

For an outside developer, the practical instruction is short: point an agent at the repository, let it read AGENTS.md, and let it pick the skill that matches the job.

A lint harness and its own test suite

The repository ships tooling for checking that the packages in it meet the standard, and the tooling is small enough to read.

{
  "private": true,
  "type": "module",
  "scripts": {
    "lint:apps": "node .tools/lint-apps.mjs",
    "test:lint": "node --test .tools/lint-apps.test.mjs"
  },
  "dependencies": {
    "yaml": "^2.8.1"
  }
}

The package is private, so nothing is published from the root, and it is an ES module. There is one dependency, yaml, which tells you the lint tool parses YAML package definitions. The two scripts are the whole build surface: lint:apps runs the linter over the app packages, and test:lint runs the linter's own test suite with the built-in node test runner.

The fact that the linter has tests is the detail worth noting. A catalogue with hundreds of directories will drift, and a check that is not itself tested becomes a check that quietly stops working. Here the rules have their own regression tests, run by the same command style anyone would use locally.

The workflow the package implies is therefore: write or update a package directory, run the linter over the apps, run the linter's tests, and submit. The rules the store enforces are implemented in the repository rather than in a reviewer's head, which is what makes the App Store Standard enforceable at all at this scale.

Badges for your own README, generated per app

Once an app is published, the project hands out badges, and the README documents both the app-specific and the generic form.

For an app, the badge endpoints take the app id, and there is a dark and a light variant:

https://apps.umbrel.com/api/app/<app-id>/badge-dark.svg
https://apps.umbrel.com/api/app/<app-id>/badge-light.svg

The README shows the Immich case as the example, with the badge image pointing at the app's page on the store, so the badge is a link as well as an image.

The generic form needs no app id and points at the store itself:

https://apps.umbrel.com/badge-dark.svg
https://apps.umbrel.com/badge-light.svg

Developers can use these in their own README, website, or release notes. For an upstream project, that is a distribution channel with real reach, and for the store it is a way to say that being packaged here is a first-class install path.

The endpoints are served from apps.umbrel.com, the same host as the store, so the badge is a static asset that reflects publication state without the publisher having to update anything. That is a small design decision with a real effect: the badge cannot go stale, because it only exists once the app is in the store.

Where this repository is the wrong place to look

The limits follow from what the repository is.

First, it is not a place to find the applications themselves. There is no source code for Immich or Actual or AdGuard Home in these directories. The packages describe how to obtain, configure and update software that lives elsewhere, so a reader looking for a self-hosted application has to go to the store, and a reader looking for the app's own code has to go to that project's own repository.

Second, there is no per-app versioning in the GitHub sense. The repository publishes no releases, so the history of an individual app's package is the git history of its directory. If you want to know what changed in a particular app's package between two moments, you read the commits touching that directory, not a release note.

Third, contribution is a packaging exercise with a fixed acceptance bar, not an open pull request to a codebase. The App Store Standard, the skills and the linter define what is acceptable before a human looks at it, which is efficient for the maintainers and restrictive for a contributor whose app has no web UI. The README does not describe a way to publish something that does not fit the standard, and the self-hosted path is a separate thing: the skills mention building a self-hosted app that can be packaged for the App Store, which is a different job from running one on your own umbrelOS.

Finally, the licence is not stated for the repository, so if you intend to reuse a package definition, as opposed to contributing one, that is a question to ask rather than assume.

Editorial conclusion

Developers who want their self-hosted app in front of umbrelOS users should contribute a package to umbrel-apps, because the App Store standard and the lint harness tell you exactly what a package has to satisfy before it is published. It is the wrong repository for anyone who simply wants to run one app, since installing from the store is the consumer path and contributing a package is the producer path. Before starting, read AGENTS.md and the skills under .agents/skills, and check that your app opens to a browser-based setup flow, since the store standard requires it.

Frequently asked questions

Official sources

1. getumbrel/umbrel-apps on GitHub
2. Issues
3. Project website
4. README