Keeping Solnix fresh

Solnix stays current because the people running it help keep it current. Every Solnix host can — if you invite it to — build packages that need building, seed the ones it already has to its neighbours, and tell the project what platforms are in use so we know where to point effort. The more hosts take part, the fresher and faster the cache is for everyone, and the less it all rests on one operator’s machines.

This is an invitation, not a default. A fresh Solnix install takes part in none of this until you opt in. This page explains what the help is, how we keep it safe, and the one setting that turns it on.

Private by default — we ask, we don’t assume

Solnix is private out of the box. A machine whose configuration never touches the participation switch sends nothing, shares nothing, and builds nothing for anyone but you. We think contributing is worth doing — so after installation your MOTD asks:

──────────────────────────────────────────────────────────────────────
 Solnix keeps its package cache fresh as a community. Your machine can
 help: build queued packages in idle time, seed what it has fetched to
 other users, and report its platform (architecture + illumos flavour,
 resolved to a country and then forgotten — never your IP or a machine
 ID) so we know where to aim effort.

 This is OFF until you choose it. To join, set in your configuration:

     solnix.privacy.enable = false;   # opt into the community cache

 Details, the trust model, and how to turn on only some of it:
     https://solnix.io/docs/handbook/keeping-solnix-fresh.html
──────────────────────────────────────────────────────────────────────

Nothing happens because the message appeared. It is a request you are free to ignore; the default stays fully private.

The switch reads backwards, on purpose and regrettably. solnix.privacy.enable = true is the default and means fully private. You opt in by setting it to false. A positively-named solnix.community.enable (default false) is planned to replace this footgun. See Privacy & telemetry.

The three ways a host can help

What’s live today. The server side of this — the signed work queue, the validate-and-sign pipeline, the BitTorrent tracker and seeder, and the census ingest — runs now. The host-side Nix options below (cache.build, cache.seed, telemetry.census) are the client contract a Solnix install wires up; where an option is still being rolled out, treat the setting as the agreed name and shape rather than a promise it is active on your image yet. Seeding and pulling over the swarm, and HTTPS cache access, work today.

Once you opt in, these default on, and you can pare back any one of them individually. Each is independent; turning one on does not turn on the others.

solnix.privacy.enable = false;        # opt into the community cache

# with privacy off, these default true — override any individually:
solnix.cache.build.enable   = true;   # build queued packages in idle time
solnix.cache.seed.enable    = true;   # seed fetched cache objects over BitTorrent
solnix.telemetry.census.enable = true; # daily platform ping (arch + illumos flavour + country)

1. Build what needs building

solnix.io publishes a signed work queue — the list of packages, rebuilds, and missing man pages the cache wants, per architecture. With cache.build.enable, your host claims an item from that queue during idle time, builds it in a sandbox, and submits the result back for validation and signing. A lease means a long compile keeps its claim, and if your machine stops mid-build the item returns to the queue for someone else. Nothing you build is served until solnix.io independently handles it (see the trust model below).

See Community build federation for the queue format and the certified-builder path.

2. Seed what you already have

With cache.seed.enable, your host seeds the public, signed cache objects it has already fetched to other Solnix users over BitTorrent. It only ever shares public Nix store paths — never your data — and because every object carries solnix.io’s signature, a seeded copy is exactly as trustworthy as one pulled over HTTPS. Pulling from the swarm is always available too, with plain HTTPS from cache.solnix.io as the guaranteed fallback.

See Peer-to-peer distribution.

3. Tell us what’s running

With telemetry.census.enable, your host sends a small daily ping reporting its architecture and illumos flavour. Your IP is resolved to a country at the edge and then dropped — never stored, never logged alongside the report. There is no machine identifier, no hostname, no store paths, no personal data. It exists so the project can see which platforms are actually in use and aim packaging effort accordingly. What it feeds is visible on the community pulse.

See Privacy & telemetry for exactly what is and isn’t retained.

The trust model: why taking part can’t hurt anyone

Letting strangers’ machines build and distribute packages sounds dangerous. It isn’t, because of one rule that never bends:

No byte is ever served that solnix.io did not validate and sign, and no client ever imports a byte whose solnix.io signature it did not verify. Community, BitTorrent, and reputation are optimisations layered on top of that — they change who finds and delivers a package, never whether it is trusted.

Concretely:

• One signer, always. solnix.io holds the single cache signing key (cache.solnix.io-1), validates every artifact — signature, hash, shape, closure — before serving it, and signs it. The key never leaves its cluster. Builders and community hosts never hold it; they submit unsigned outputs and solnix.io signs them.
• Trust is reproducibility, not opinion. The only thing that promotes a community-built package is that someone independently rebuilt it and got the same bytes. That is Sybil-proof: a thousand fake identities still cannot make a malicious package reproduce. A single hash mismatch where others agree is investigated, not averaged away.
• The client checks the signature before importing. So a hostile seeder or a tampered torrent can waste your bandwidth and nothing more — Nix refuses an object whose solnix.io signature doesn’t verify.
• Keys are revocable. Builder and proposer keys can be revoked fast and a re-check sweep run; clients fetch the revocation list.
• No personal data in the trust decision. Nothing about who you are affects whether your bytes are trusted — only whether they reproduce. Builder identities are public keys, not names; attestations carry key-ids; solnix.io never stores swarm IPs. If you choose to give a contact email when enrolling as a builder (see below) it is used only to reach you about your builds — it is never published, never aggregated, and never part of the trust calculation.

If you build and submit a package, the worst a mistake can do is cost you some reputation and a reviewer’s time — it can never put a bad byte into anyone’s store. That is the whole point of the design: participation is safe because the trust root is a single auditable signer and independently reproducible bytes, not the honesty of the crowd.

Becoming a trusted builder: identity, by invitation

Seeding and the anonymous census ask nothing about who you are. Becoming a trusted builder — a host whose independently-reproduced bytes can promote a package into the cache — is different: trust needs continuity, so it needs an identity. This is a separate, explicit opt-in, above the three toggles.

solnix.builder.enable       = true;              # enrol this host as a builder
solnix.builder.contactEmail = "you@example.org"; # OPTIONAL — omit to stay unreachable

• Your SSH key is your builder identity. Enrolment registers your host’s ssh-ed25519 public key with solnix.io. That one key is your builder identity — there is no separate account and no password. Reputation and trust tier attach to the key.
• The trust gate. A host can only become a trusted builder if it both sends telemetry (we can see it) and has registered an SSH identity (we can identify it). A host that submits builds without enrolling stays advisory: another enrolled builder can independently reproduce its bytes and submit them through the signed path, but the un-enrolled host holds no trust tier itself. Enrolling makes you eligible — tier is still granted by a human operator, never self-assigned.
• Optional contact email. You may include an email so we can reach you if something needs attention — your builds stopped reproducing, your key is being retired. It is optional, off unless you set it, never shown publicly, never in any aggregate, and removable (clear the setting). The anonymous census never carries it.
• Rotating your key, without losing your reputation. When you replace your SSH key, you tell solnix.io about the new key in a record signed by the old key (and by the new one, to prove it exists). solnix.io checks the old key is still valid and the new key isn’t already taken, then moves your trust, reputation and contact details to the new identity and retires the old. Your standing follows you across a key change; a revoked key cannot rotate.

What’s live today. The one-signer validate-and-sign path, the work queue, and the tracker/seeder run now. Self-service builder enrolment, the SSH-signed rotation, and the telemetry-plus-identity trust gate are the agreed contract being wired up between the hosts and solnix.io; treat the settings above as the committed names and shapes, not a promise they are active on your image yet.

The full technical design lives in the infra repository (docs/design/community-build-federation.md, docs/design-p2p-trust-validation.md, docs/design-telemetry-ask.md).

Turning it off again

Remove the opt-in — or set the master switch back — and your host returns to fully private immediately:

solnix.privacy.enable = true;   # back to fully private: no build, no seed, no ping

Or keep the parts you like and drop the rest; each of the three is an independent toggle under the opt-in. The master switch always wins: with privacy.enable = true, nothing participates no matter what the individual toggles say.