Spegel: a stateless OCI registry mirror that runs inside your Kubernetes nodes

The problem Spegel solves on a node that already has the image

Every node in a cluster pulls the same base images from the same external registries. When Docker Hub rate-limits a cluster, or a registry has an outage, new pods sit in ImagePullBackOff even though the image bytes are already on a neighbouring node's disk. Spegel's README lists exactly this set of motivations: locally cache images from external registries with no explicit configuration, avoid cluster failure during external registry downtime, improve pull speed and pod startup time by pulling from the local cache first, avoid rate limiting, decrease egress traffic, and increase pull efficiency in edge deployments.

The intended audience is stated plainly in a note near the top of the README: the project focuses on the home lab and individual contributor use case, the API is evolving, and support is best-effort. That is a narrower promise than a production registry vendor makes, and it should shape how you read the feature list. Spegel is not a place to store images. It is a distribution layer that assumes the image already exists somewhere it can be fetched from.

How the peer-to-peer mirror works, from the dependency list

The README is short and does not describe the architecture, but go.mod does. Spegel is a Go program built on go-libp2p and go-libp2p-kad-dht, the Kademlia distributed hash table implementation. That is the mechanism: nodes form a peer-to-peer network and use a DHT to advertise which content they hold, keyed by content identifier. The go-cid, go-multiaddr, go-multicodec and go-multihash dependencies are the addressing and hashing layer for that DHT, so lookups are content-addressed rather than host-addressed.

On the registry side, the module requires containerd v2, the containerd API, containerd errdefs, containerd platforms and typeurl. The README's claim of caching with no explicit configuration is consistent with that: the mirror reads image content through the containerd content store rather than maintaining a separate cache directory. A pull for a digest that a peer already has can be served from that peer instead of the external registry. The project also depends on cuelabs.dev/go/oci/ociregistry, the OCI registry client, and on the OCI image-spec and go-digest packages, which is what makes it a registry mirror rather than a generic file-sharing layer.

Two smaller details are worth noting. Spegel pulls in prometheus/client_golang, so metrics are part of the design, though the README does not document an endpoint. It also uses go-toml/v2 and go-arg, which suggests a config file and a command-line parser, but the README does not list flags. For both, the getting started guide is the place to look, not the README.

Installing Spegel and pointing it at a first image

The README does not contain install steps. It says: read the getting started guide to deploy Spegel, linking to https://spegel.dev/docs/getting-started/. The repository also ships a Helm chart under charts/spegel, and the Makefile shows that the chart's README is generated from values.yaml with helm-docs, so the chart values file is the authoritative list of configuration keys.

What can be confirmed from the repository is how the container image is built. The Dockerfile copies a prebuilt binary from the dist directory into a distroless static nonroot base image and sets the entrypoint:

FROM gcr.io/distroless/static:nonroot
ARG TARGETOS
ARG TARGETARCH
COPY ./dist/spegel_${TARGETOS}_${TARGETARCH}/spegel /
USER root:root
ENTRYPOINT ["/spegel"]

The Makefile shows the image name used by the project's own integration tests, ghcr.io/spegel-org/spegel, tagged with the short git commit hash:

IMG_NAME ?= ghcr.io/spegel-org/spegel
IMG_REF = $(IMG_NAME):$(TAG)

If you build from source, the Makefile provides the targets. The build target runs goreleaser in snapshot mode, and build-image then builds with docker buildx:

make build
make build-image

For a first real use, the honest answer is that the deployment path is the Helm chart plus the getting started guide, and the first thing to verify is that your nodes use containerd. Spegel's dependencies are containerd-specific. If your cluster runs a different container runtime, the containerd content store that Spegel reads from is not there, and the mirror has nothing to serve. The README gives no instructions for other runtimes.

Where Spegel is the wrong tool

Spegel is stateless, and that word does real work. There is no persistent image store, no garbage collection policy, no replication factor and no archival tier. If an image disappears from the upstream registry, Spegel cannot reconstruct it; it can only serve what some node already pulled. A team looking for a registry of record, with retention rules and audit trails, is looking at a different class of software.

The support model is the second constraint, and it is explicit. The README says the project has an evolving API and no guaranteed support, with assistance on a best-effort basis, and that the focus is the home lab and individual contributor use case. Treating Spegel as a supported dependency in a regulated environment means accepting that a minor release can change behaviour. The release list supports the caution: v0.8.0-rc.1 is a release candidate, and the project is still in the 0.x range.

Finally, peer-to-peer distribution has an operational cost that a central cache does not. The DHT and libp2p layer needs connectivity between nodes, and the benefit depends on images being pulled more than once across the cluster. A single-node cluster, or one where every image is unique, gets little from it.

Spegel compared with Dragonfly and Harbor

The two comparisons people search for most are Dragonfly and Harbor, and the difference is architectural rather than a matter of features.

Dragonfly also distributes image layers peer to peer, but it does so through dedicated supernode and peer components that form their own cluster-level caching system. Spegel takes the opposite approach: it runs as a mirror on the nodes and relies on containerd's own content store, using a Kademlia DHT rather than a supernode topology to find content. The practical consequence is that Spegel has no separate cache cluster to size or operate, and also no central component that knows the state of the whole cache.

Harbor is a registry, not a peer-to-peer distributor. It stores images, scans them, replicates them between registries and enforces policy. Spegel stores nothing and enforces nothing; it points at registries and serves content that nodes already have. They solve different problems and can sit in the same cluster, with Harbor as the upstream and Spegel as the node-local mirror in front of it.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-22, one day before this article's reference point, so the codebase is being changed. The release cadence in the recent list is roughly every two weeks to two months: v0.7.3 on 2026-07-01, v0.7.4 on 2026-07-15, and v0.8.0-rc.1 on 2026-09-02. The presence of a release candidate rather than a final v0.8.0 at that point is the upgrade signal to watch: if you deploy the chart, pin the image tag rather than tracking a floating tag, because the API is described as evolving.

The licence is MIT, which permits commercial use and modification with the copyright notice retained. That is a permissive licence and imposes no copyleft obligation on your own code. It says nothing about support, and MIT does not create any warranty, which is consistent with the README's best-effort statement. If your organisation requires a support agreement, the licence is not where that comes from.

The repository also contains SECURITY.md, CONTRIBUTING.md and an AI_POLICY.md, so there are documented processes for reporting issues and contributing. The Makefile defines the test surface: go test with the race detector for unit tests, plus separate integration suites for containerd and for Kubernetes, the latter building the image first and passing IMG_REF into the test. Running those suites is the realistic way to check a change against your own environment.

Editorial conclusion

Spegel fits home labs, individual contributors and edge clusters that pull the same images repeatedly and want to survive an external registry outage or a Docker Hub rate limit. It does not fit teams that need a guaranteed support contract, a stable API, or a registry that stores images for archival: Spegel holds nothing itself and the README states the API is evolving with no guaranteed support. Before adopting it, check the getting started guide at spegel.dev, confirm your container runtime is containerd, and read the chart values to see which mirror registries are configured.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spegel-org/spegel on GitHub