Community build federation
Solnix’s binary cache is built to be a community effort, not a single operator’s burden. Anyone running Solnix can help build packages, help deliver them, and (as trust is earned) help decide what gets cached — without ever being able to slip a compromised package to anyone else. This page explains how that works and how you can take part.
The one guarantee that makes it safe, stated up front:
No byte is ever served that solnix.io did not validate and sign, and no client ever imports a byte whose site signature it did not verify. Everything else — the community, BitTorrent, reputation — is optimization on top of that.
Who does what
- solnix.io is the sole signer. It holds the cache signing key, validates
every artifact (signature, hash, shape, closure) before serving it, and signs
it with
cache.solnix.io-1. The key never leaves its cluster. - Certified builders are enrolled identities that build the work queue (and, in the design, would adjudicate community proposals). They never hold the signing key either — they submit unsigned build outputs and solnix.io signs them.
- Community instances — you, running Solnix — can seed packages to lighten the load. Proposing packages over BitTorrent and earning a reputation is a design, not built yet (see below).
- Everyone pulling packages prefers BitTorrent and falls back to HTTPS.
There is no single point of failure in delivery (the swarm plus HTTPS). There is deliberately a single point of trust — one signer — because that is what keeps the cache safe.
The work queue is public
solnix.io’s build TODO list — which packages, which architectures (x86_64,
aarch64, riscv64, UltraSPARC sparcv9), which rebuilds — is a live API on
builders.solnix.io, readable by anyone:
GET https://builders.solnix.io/api/v1/build-queue/rows?system=aarch64-solaris
GET https://builders.solnix.io/api/v1/build-queue/view
The queue page shows the same data. There is no
published signed work-queue.json file; reading is open, and claiming an item
needs an enrolled builder key (claims are signed with it, sshsig). A claim
carries a lease, so a long compile keeps its claim.
The order is: security fixes first, then infrastructure and toolchains, then the maintainer’s focus set (the packages the maintainer’s own machines use, and the COSMIC desktop), then everything else. Within a class, a package’s dependencies come before it, then the more-downloaded package (counted from real cache downloads) goes first.
Each item says what kind of work it is: a package at a target version (with the configuration its recipe specifies), a dependent that needs rebuilding because one of its dependencies changed, a package that is missing its man pages, or a rebuild after a validation failure.
Builders: an SMF service, hands-off
A builder host runs solnix-builder as an SMF service that loops on its own. It
is a plain script — no AI in the loop — because the queue entry plus the package
recipe fully specify every build. How much of the machine it takes is set by a
profile (solnix.cache.build.profile):
idle(the default): one job, only when the host is quiet.opportunistic: for a machine someone uses. It builds in up to 2/3 of the CPUs other work leaves idle, under a kernel CPU cap at 66%.dedicated: for a build host. It uses every idle CPU, back to back while the queue has work.
The build fleet today is three hosts: dixi (x86_64) and dixa (aarch64) run
dedicated, and lixi runs opportunistic.
What a host builds today is a reproduction. It rebuilds a package that is already in the cache, checks that its bytes match the served NAR, and only then claims the queue item and marks it done. That verifies the cache; it does not add new packages. A package’s first build reaches the cache through the build team’s submitter, which uploads the unsigned outputs to solnix.io’s staging for the site to validate and sign. A path for hosts to submit their own first builds for operator approval is being built (target 2026-11-06); it is not live yet.
Leases and heartbeats mean a long compile keeps its claim, and a builder that dies mid-build has its job returned to the queue for someone else. Many builders can run with no coordinator; the queue is the coordinator.
The submit protocol is in the infra repo’s docs/handoff/builder-onboarding.md;
the client side is in the solnix repo’s docs/cache-submit-onboarding.md. For
how an ordinary opted-in host joins in building, seeding and the platform
census, see Keeping Solnix fresh.
Proposing a package (design, not built)
Not built yet. Proposing over BitTorrent, proposer keys and reputation scores (this section and the next) are the design. None of it runs today.
The design: if you are running Solnix and you have built a package the cache wants, you could propose it even without being a certified builder:
- You build it and make a deterministic torrent of the result (fixed piece length, no timestamps, so honest builders of the same package produce the same torrent).
- You sign a small proposal record with your proposer key (a handle you generate once; it is not a signing key and grants no write access) and post it to solnix.io, then seed the bytes to the swarm.
- A certified builder picks up your proposal and independently rebuilds the same package. If their bytes match yours, your proposal is real: they submit it through the normal signed flow, solnix.io signs and serves it, and your reputation goes up. If the bytes do not match, the proposal is rejected and your reputation takes a hit — a mismatch is a loud signal, not an average.
Your proposal is only ever advisory. It can save a certified builder the trouble of discovering the work, but it can never put bytes into the cache that a certified builder didn’t independently reproduce and solnix.io didn’t sign. A bad proposal costs you reputation and some adjudication time; it cannot harm anyone.
Reputation (design, not built)
In the design, every proposer key accrues a reputation score, stored on solnix.io and published (signed) so other peers can read it. The score moves on reproducibility, not popularity:
- big increase when a certified builder independently reproduces your bytes;
- small increase for a well-formed proposal that passes structural checks;
- big decrease (and possible revocation) when your bytes don’t reproduce or you claim a hash you didn’t actually produce.
Because the only way to gain real reputation is to produce bytes that others independently reproduce, running a thousand fake identities buys nothing — you still can’t make a malicious package reproduce. Reputation would decide whose proposals get looked at first and which seeders peers prefer to pull from; it would never be used in place of the mandatory signature check.
BitTorrent-first delivery
When your Solnix host needs a package, it:
- fetches the tiny signed
narinfofromcache.solnix.io(over HTTPS), - reads the torrent reference in it and pulls the actual package bytes from the swarm (preferring higher-reputation seeders, once reputation exists), and
- falls back to HTTPS from solnix.io if the swarm is slow or has no seeders.
Either way, Nix verifies solnix.io’s signature before importing anything — so a hostile peer can only waste your bandwidth, never install a bad package. Pulling from the swarm lightens the load on solnix.io; seeding what you have helps your neighbours. Both are opt-in (seeding exposes your IP to peers, so it is off by default — see Peer-to-peer distribution and Privacy & telemetry).
Why this is secure and self-governing
- Trust is reproducibility, not opinion. The only vote that counts is “I built it and got the same bytes.” That is Sybil-proof: fake identities can’t reproduce malicious bytes.
- One signer, every time. Everything served is signed by solnix.io after its validation gate. Community and BitTorrent change discovery and delivery, never the trust root.
- The client always checks the signature before importing, so a compromised delivery path is a bandwidth nuisance, nothing more.
- Disagreement is an alarm. A single hash mismatch where others agree is investigated, not averaged away; suspect objects are quarantined for forensics, never silently dropped.
- Keys are revocable, fast. Builder and proposer keys can be revoked and a re-quarantine sweep run; clients fetch the revocation list.
- No personal data. Proposer keys are self-generated handles, attestations use key-ids or rotating nonces, and solnix.io never stores swarm IPs.
The aim is a cache that the whole community builds, delivers, and helps govern — fast, resilient, with no single point of failure in delivery — while remaining impossible for a bad actor to poison, because trust rests on independently reproducible bytes and a single, auditable signer.
The full technical design is in the infra repository:
docs/design/community-build-federation.md and
docs/design-p2p-trust-validation.md.