Documentation
The pool, chapter by chapter
Pick a chapter, or type what you are looking for — the map on the left is on every page of the documentation, and every section is one link. Everything is documented here, where it runs: how to use the pool and who decides what, and below, the code itself — its architecture, runbook, tests and the rest — for people working on the pool. The repository on GitHub is where the code lives and is released.
Get started →
Point pacman at a ring: the one command, or the key and the sections by hand; the thin client; switching rings.
omarchy-cli as an MCP server →
omarchy-cli mcp serves the client's answers as tools over the Model Context Protocol (stdio transport: one JSON-RPC 2.0 message per line on stdin and stdout), so an assistant running on the machine can reason about the ring and the system without shelling out and parsing text. Everything is read-only — the tools answer, they never install, upgrade or pin.
Run a worker →
One signed image, with Docker or Podman: your own packages, the project's jobs — the registration decides, not the image.
How it works →
Where every package comes from, the gates it passes, what protects you — and what the pool does for the people who bring packages in and the people who decide.
What we test →
Every package the factory builds passes the same gate before it is evidence, and a group of packages — a desktop app, a prebuilt binary — must do more. This page is that list, written once: the agents that draft and audit recipes read exactly this text as their skills, the gate enforces what a program can enforce, and a maintainer decides last, on the evidence of both.
Governance →
Two roles, one file, decisions by pull request: contributors and maintainers, the project's workers, blocking, becoming a maintainer, the record.
Security →
Five public feeds matched every three hours against what each ring serves; how sure a match is; the fast-track.
Glossary →
The words on these pages, one line each.
API →
Every endpoint the dashboard and the tools use, with examples.
For people working on the pool
Architecture →
omarchy-pool is a package repository for Omarchy built on three ideas: an immutable package pool plus an index that represents complete releases, signed pacman databases generated from that index, and a thin client that understands releases. It began as a proof of concept answering exactly those three questions — the evidence is kept in poc/RESULTS.md — and now runs as the staging environment at https://omarchy-pool.firemanxbr.org.
Runbook →
Operating the staging environment. Nothing here is done by hand on the servers: every write goes through the Worker with a per-job token a worker got at claim time; there is no shared secret. Humans operate the pipeline by queueing jobs (pkg-repo job, or the API with a maintainer's token) that project workers run.
Testing →
Everything runs on a developer machine without root and without touching production. Real Arch packages are used as fixtures wherever the behaviour depends on the archive format.
Migration →
How to move omarchy-pool from one GitHub account and one Cloudflare account to others — for instance from firemanxbr to the Omarchy foundation — starting from a copy of this repository. Every step is a command or a click; nothing depends on the old accounts once it is done. Budget an afternoon, plus the hours the first full import takes on a project worker.
The factory →
Builds the packages no upstream ships — for the architectures the pool serves but nobody else covers (today: what the OPR only builds for x86_64, on aarch64), and, later, the AUR names Omarchy installs. It lives in this repository for now; it is designed to move out (see The contract and docs/MIGRATION.md).
The worker host →
What the project runs its workers on: one machine, six containers of the one worker image — two of each role, one per architecture (the roles: factory/README.md Three roles; how the day goes: docs/RUNBOOK.md The Studio host). Anyone donating a machine to the project can use the same three files.
Security model →
How omarchy-pool decides who may do what, where the keys live, and what a compromised piece can and cannot do. Decisions are recorded here as they are made; the Status column says what is running today.
Contributing →
Everything in the repository — code, documentation, commit messages — is in English.
The proof of concept →
omarchy-pool started as a proof of concept for the Omarchy repository migration, built to answer three questions from the packaging team:
Open work →
Open work, roughly in order of value for effort. The POC questions are answered (see poc/RESULTS.md) and the staging environment runs the whole pipeline on every upstream repository; everything here is what would turn it into something the migration can rely on. Pick an item, open a pull request (see CONTRIBUTING.md), and keep docs/TESTING.md in step with what you add.