OmaStore indexes standalone apps for Omarchy (not plugins or themes)
straight from GitHub. There is no sign-up, but there is one requirement: the
repository must have an omastore.toml at its root (section 6). Without it,
the repository is not added to the catalog, even with the omarchy topic. The
file may even be empty: its presence is the signal that you want the app in the store.
Shortcut: the skills in
skills/do this with your coding agent (Claude Code, Codex, OpenCode, Copilot, Gemini, Cursor, Pi, Hermes…):omastore-manifestwrites the manifest,omastore-releasesets up the releases andomastore-checkaudits everything. OmaStore'sinstall.shalready puts them in every installed agent's skills directory; the pacman package (andmake install) only ships them in/usr/share/omastore/skills, so copy them from there.
-
Have
omastore.tomlat the root of the default branch: the store finds repositories through GitHub code search for that file, even without a topic. -
Add the
omarchytopic to the repository (Settings → Topics). -
Add topics that describe the app; they define its category in the catalog:
Category Example topics Graphics photo,image,design,drawing,annotationAudioVideo audio,music,video,voice,speech,recorderDevelopment developer-tools,editor,git,databaseNetwork email,browser,chat,vpn,bluetoothOffice notes,calendar,pdf,productivitySystem virtualization,monitor,hyprland,backupGame game,emulatorWithout topics, the category is inferred from the description and falls back to Utility if nothing matches.
-
The
cli,tuiorterminaltopics make the launcher open in a terminal (on Omarchy, throughomarchy-launch-or-focus-tui). -
The body of your latest release is shown on the app's page as "What's new": write release notes for people, not only a list of commits.
-
Archived repositories are left out; forks do not show up in the topic search.
-
If multiple repositories publish an app with the same display name, the catalog shows the one with more GitHub stars. Equal star counts favor the older repository. Installed copies remain visible on the Installed page.
Only the latest stable release (not a pre-release) is considered. Name the assets with the system and architecture:
myapp-1.2.0-x86_64-linux.tar.gz
myapp-1.2.0-aarch64-linux.tar.gz
- Recognized architectures:
x86_64/amd64/x64andaarch64/arm64. - Formats, in order of preference:
.tar.gz,.tar.xz,.tar.zst,.tar.bz2;.zip(needslinuxor the architecture in the name);- plain binary (same);
.AppImage;.pkg.tar.zst.
- Ignored:
.deb,.rpm,.dmg,.exe,.msi, source tarballs (source,src) and assets withdarwin,macos,windowsetc. in the name.
Prefer a portable tarball. From .pkg.tar.zst packages only the
contents of usr/ are extracted (.INSTALL scripts never run). Since
everything lives in $HOME, not in /usr, programs that look for data at
absolute paths such as /usr/share/myapp do not work.
Inside the package, the main executable is chosen by, in this order:
- having the same name as the repository;
- being in
bin/orusr/bin/; - being ELF (not a script).
.so libraries and files in lib/ and share/ are ignored. Scripts
need the executable bit and a shebang.
The command installed in ~/.local/bin is a small launcher that calls the
absolute path of your binary, so $0/argv[0] point to the real file and
paths relative to it ($(dirname "$0")/../lib) work.
The command name cannot collide with a system command (/usr/bin/...):
the installation is refused so it does not shadow, for example, ls or sudo.
OmaStore checks the sha256 that GitHub itself computes for each asset
(the digest field). If you prefer to publish your own, any of these works:
myapp-1.2.0-x86_64-linux.tar.gz.sha256(just the hash, orhash name);checksums.txt/SHA256SUMSinsha256sumformat, or the BSD formatSHA256 (name) = hash.
If the hash does not match, nothing is installed. Releases without any checksum ask the user for confirmation.
A checksum proves the download arrived intact, not which code built it. Add
actions/attest-build-provenance
to the workflow that builds the release (the omastore-release skill does):
permissions:
contents: write
id-token: write
attestations: write
steps:
# ... build the tarballs ...
- uses: actions/attest-build-provenance@v4
with:
subject-path: dist/*.tar.gzOmaStore verifies the attestation with Sigstore when it indexes the release:
it must be signed by a GitHub Actions workflow of your own repository
(a reusable workflow elsewhere does not count) and name the exact file. The
app page then shows "Built by this repository's GitHub Actions" with the
workflow and tag, and users who turned on Install only apps with build
provenance can install it. omastore check you/myapp reports it.
- Publish a stable GitHub release first. Until one exists, OmaStore does not fetch the README or repository images, so the app has no preview.
- Icon: an
icon.svg/icon.pngat the root, inassets/,icons/,resources/ordata/. Names such as<repo>.svg,logo.svgandapp-icon.pngalso work, as does theicons/hicolor/<size>/apps/layout. SVG is preferred; a PNG of at least 256×256 is resized for the theme. - Screenshots: the README images (badges are ignored) and files in
folders or with names containing
screenshot,previewordemo. Up to 8 are shown in the app page's carousel. README images are not repeated inside the displayed README text.
For predictable results, commit the images and name them in the manifest:
myapp/
omastore.toml
assets/icon.svg
screenshots/main.png
icon = "assets/icon.svg"
screenshots = ["screenshots/main.png"]Declared screenshots replace the automatically found ones. They may be paths
relative to the repository or https:// URLs. Each image must be a supported
PNG, JPEG, WebP, GIF or SVG and no larger than 15 MiB; otherwise it cannot be
displayed. The carousel keeps the image's aspect ratio.
- The summary is the repository description (the short sentence at the top on GitHub); if it is empty, the first paragraph of the README.
- The display name is the repository's, with the spelling of the README's first
heading when they match (e.g. repo
omaphoto, heading# OmaPhoto). - The README is shown on the app page, with relative links converted to absolute ones.
- A root
CHANGELOG.mdis shown after the README, with relative links converted to absolute ones. Repositories without one need no extra file request.
If your app needs system packages (Qt, GTK, ffmpeg...), keep a PKGBUILD, or
better its .SRCINFO, in the repository: at the root or up to three
directories deep (packaging/arch/, aur/...). OmaStore reads its depends
and optdepends (and depends_x86_64/depends_aarch64), shows them on the
app page and offers to install the missing ones with pacman after the app is
installed.
- The
PKGBUILDis never run: only literal arrays are read. An element with$var,$(...)or a glob is dropped, so prefer committing a.SRCINFO(makepkg --printsrcinfo > .SRCINFO), which has the final values. - With several files, a
.SRCINFOwins over thePKGBUILDin the same directory, a directory withbinin its name (your-binpackage) wins over others, and shallower wins over deeper. For split packages, the one named after the repository is used (or<repo>-*). makedependsandcheckdependsare ignored: the store installs your release binary, it does not build it.- Packages only in the AUR are shown as unavailable and never installed by the store; users install them themselves.
The file must exist at the root of the default branch. All fields are optional; whatever is not declared is inferred by the rules above. Declare what the heuristics would get wrong (icon, executable, asset).
kind = "app" # default; "plugin" and "theme" are not indexed
name = "RAWmakase" # display name
summary = "Free alternative to Lightroom" # summary (up to 300 characters)
categories = ["Graphics", "Photography"] # freedesktop; the 1st main one becomes the category
icon = "packaging/rawmakase.svg" # PNG or SVG, path in the repository
screenshots = ["docs/images/screenshot.png", "https://example.com/screen.png"]
terminal = false # open in a terminal?
[linux.x86_64] # or aarch64
asset = "rawmakase-{version}-x86_64-linux.tar.gz" # {version} = tag without "v"; {tag}; *
exec = "usr/bin/rawmakase" # executable inside the package ({version}/{tag} work here too)The catalog groups Audio, Video, and AudioVideo under Audio/Video.
The original manifest categories are kept in the installed .desktop file.
Rules:
- Paths: must be relative and stay inside the repository (or the
package, for
exec). Anexecthat is a symlink pointing outside the package is refused. - Asset: the declared one takes priority over the automatic choice and is accepted even with a name the heuristics would not understand. If the pattern does not match any asset of the release, the app is not installable on that architecture (the store does not guess, so it never installs a file you did not mean). Architectures the manifest does not declare use the automatic choice.
- Invalid fields: are ignored, with a warning; the rest of the manifest still applies. A file that is not valid TOML removes the repository from the catalog, so validate it before publishing.
- Apps only:
kind = "plugin"or"theme"(or any value other thanapp) keeps the repository out of the store.
An app with a background part (a daemon, a session helper) declares it and
OmaStore generates a systemd --user unit for it in
~/.config/systemd/user, pointing at the executable of the installed version:
[services.sessiond] # ID: letters, digits, _ or -
type = "systemd-user" # the only type
unit = "myapp-sessiond.service" # unit name, no path
exec = "usr/bin/myapp-sessiond" # executable inside the package
enable = true # start at login (default false)
start = true # start now, after installing (default false)
restart = "on-failure" # or "no" (default)- The packaged
.servicefile, if any, is neither copied nor run: its/usr/binpath would be wrong for an installation in$HOME. There are no install or uninstall commands. - Unlike other fields, an invalid service declaration (unknown field or type,
bad unit name,
execleaving the package) keeps the app out of the catalog until it is fixed: a service is never half applied. - A unit with the same name that OmaStore did not create is a conflict, not overwritten. An update restarts the service only if it was running; uninstalling stops and disables only what OmaStore enabled or started.
- The service runs with the user's privileges and needs a working user
manager (
systemctl --user).
Validate before publishing:
omastore lint-manifest . # in the repository directorylint mode is strict: a misnamed field (e.g. icone) is an error.
Indexing is lenient, so that fields from future versions do not break anything.
omastore://owner/repo opens your app's page in OmaStore (a window that is
already open shows it instead of opening another). Put it in your README:
[Get it on OmaStore](omastore://you/myapp)GitHub does not render links with unknown schemes, so on github.com also say how to find the app by name; the link works in local viewers, chats and web pages that keep it.
The quickest way is the Publish your app page in OmaStore (or
omastore-gui --check you/myapp): type the repository and it lists what passes,
what fails and how to fix it, previews the catalog card and suggests an
omastore.toml built from your latest release. Tick Test an omastore.toml
before pushing it to try a local file. The same report is on the command line:
omastore check you/myapp # published manifest
omastore check --manifest omastore.toml you/myapp # local file, before pushing
omastore check --json you/myapp # for CI; exit code 1 = not compatibleThe check downloads the selected release files for both architectures and opens them in temporary directories. It verifies their checksums, extraction, executable and declared service executables without running them. It also fetches the catalog images to confirm they can be displayed. It writes nothing to your catalog and does not install the app. The check can take time and use significant bandwidth for large releases. A failed download leaves the result incomplete, so it is reported as a failure to retry.
Content quality and runtime behavior still need a person: read the release notes and description, and test a real installation to confirm startup, user services, dependencies and the menu entry:
omastore index you/myapp # indexes only your repository
omastore show you/myapp # shows what was understood (assets, icon, category)
omastore install you/myappIf something was detected wrongly, declare it in omastore.toml (section 6) or open
an issue.