getknit/knit-spool repository overview

⁠knit-spool

The reference spool — a scoped, blinded store-and-forward relay for Knit⁠'s Internet plane.

It holds sealed frames for scope ids it cannot map to anyone, and forgets everything else.

⁠What a spool is

A spool holds, per conversation scope, a bounded set of end-to-end-sealed frames and a digest over them, streams new arrivals to connected subscribers, and heals divergence by digest anti-entropy.

It never learns node ids, message content, rosters, or delivery facts — it stores ciphertext for scope ids it cannot map to anyone. Spools never talk to each other: clients multi-home across several spools and union them, so no spool is load-bearing and a wiped spool is refilled by any one conversation member.

The protocol spec is the product. The normative spec lives in the Knit repo (docs/SPOOL_PROTOCOL.md⁠); this daemon implements it, and its test suite pins the implementation to the spec's §13 vectors byte-for-byte. Third-party spool implementations are first-class — this image exists so nobody has to write one.

⁠Quick start

docker run -p 9470:9470 -v spool-data:/data -e SPOOL_POW_BITS=20 getknit/knit-spool:latest

The daemon persists to the /data volume, runs as uid 65532, and carries a /healthz HEALTHCHECK. It serves plain WebSocket — TLS terminates at a reverse proxy; the repo ships Caddy and nginx configs plus a compose file that issues and renews certificates for you.

⁠Tags

Every release is tagged with its version, and a release that is not a prerelease also moves latest. Pin the version in production, or a @sha256: digest for the strict form. latest moves under you, and a restart on a moved tag brings back a daemon you never tested.

⁠The same image lives in two registries

The release workflow builds one multi-arch manifest and pushes that manifest to both, so these are the same bytes:

The provenance attestation is pushed to GHCR alone — it travels over the OCI referrers API, which Docker Hub supports unevenly. Verifying there covers this copy too, since both names resolve to the same digest:

gh attestation verify oci://ghcr.io/getknit/knit-spool:<version> --repo getknit/knit-spool

⁠Configuration

Environment variables only; invalid values refuse to start, and an unrecognized SPOOL_* name is logged as a probable typo. Defaults follow the spec's §12 constants.

⁠Operating

GET /healthz for liveness, GET /metrics for Prometheus text (token-gated with ?k= on private spools; the shipped proxy configs seal it off from the internet, so scrape it from inside your network). The bearer token rides in the query string, so keep it out of proxy access logs — the shipped configs already do.

Every SPOOL_STATUS_MS the daemon logs one status line, which is the docker logs -f view of a spool with no Prometheus in front of it. On a metered link, watch knit_spool_egress_bytes_total — fan-out means one push leaves as (subscribers − 1) copies, and on cheap VPS tiers the monthly transfer allowance binds long before CPU or memory does.

⁠Build your own

The route to take if you have modified the daemon:

git clone https://github.com/getknit/knit-spool && cd knit-spool
docker build -t knit-spool .
docker run -p 9470:9470 -v spool-data:/data -e SPOOL_POW_BITS=20 knit-spool

Dockerfile compiles from source; Dockerfile.dist is what the release workflow publishes — the same runtime stage over a distribution built ahead of time, which is how the arm64 image avoids an emulated compile.

⁠Conformance

The repo ships a conformance suite that validates any spool implementation — this one or a third party's — over a live connection. TAP on stdout, a MUST tally on stderr, exit 0 only when every MUST check passed.

⁠Links

• Source, issues, pull requests: https://github.com/getknit/knit-spool⁠
• Protocol spec: https://github.com/getknit/knit/blob/main/docs/SPOOL_PROTOCOL.md⁠
• Hosting guide: https://github.com/getknit/knit-spool/blob/main/HOSTING.md⁠
• Security policy: https://github.com/getknit/knit-spool/blob/main/SECURITY.md⁠

Licensed AGPL-3.0-or-later. A best-effort hobby project, shipped as-is.