--- name: solnix-builder description: > Operate a Solnix builder or understand the binary cache: the rebuild queue, the submit flow (unsigned NARs, the site signs), reproduction votes, publish gates. Use when running a builder, submitting to cache.solnix.io, or explaining why a path is or isn't served. license: CC0-1.0 metadata: author: solnix version: "0.1.0" persona: builder status: draft from the build team's builder-queue steering and site/skills SOLNIX-CACHE-OPERATOR; awaiting build-team review (phase 4) --- # Solnix: builder and cache operator **Draft.** Drawn from the build team's [builder-queue.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/builder-queue.md) (solnix 5a8e5ce) and the cache runbooks. The build team reviews it before it is final. ## Tools this uses `package_status`, `list_systems` (this server); `curl`, `nix` (standard commands). ## What a builder does 1. **Claims a job** from the queue (`POST /api/v1/build-queue/claim`), builds the attribute named by the served recipe row for (pname, system, target version). 2. **Gates it** (store-only RUNPATH, every NEEDED resolved, references complete). 3. **Submits one leaf per submission**, unsigned: `/api/v1/cache/submit/begin`, upload, `/finalize`, poll `/status/`. The site walks the closure, checks, and signs with the 8UNr key. An unpublished reference is rejected (deps first). 4. **Completes the job** with `done` (store path, NAR hash) or `failed` (the reason). Builder write routes answer only on `builders.solnix.io`. Participation is opt-in (`steering/privacy.md`). ## Read the state of a package `package_status {pname}` gives served rows (with the commit of the batch that added each), whether the narinfo is served, reproduction votes, open CVEs and the queue state. The queue rows are public at `GET https://solnix.io/api/v1/build-queue/rows?pname=

`. ## Reference - `steering/reproducibility-as-trust.md`, `steering/trust-and-signing.md` - [handbook: keeping Solnix fresh](https://solnix.io/docs/handbook/keeping-solnix-fresh), [handbook: community build federation](https://solnix.io/docs/handbook/community-build-federation)