Spegel mirrors images without configuration, and asks for best-effort support
Stateless cluster local OCI registry mirror.
At a glance
- What is it?
- Spegel is a stateless, cluster local OCI registry mirror written in Go, whose stated purpose is to cache images from external registries with no explicit configuration so that pull speed, registry downtime and rate limits stop being cluster problems. Its dependencies show a distributed hash table and containerd underneath, and its Dockerfile claims a nonroot base image before switching to root.
- Who is it for?
- Spegel suits a home lab or a small cluster where pulling from Docker Hub is slow, rate limited, or a single point of failure when the registry is down. It does not suit a production platform with a support contract, because the project states its API is evolving and support is best effort, and it is not a replacement for a garbage collecting registry such as Harbor or Kraken, since nothing is stored deliberately.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- spegel-org/spegel3,834 ★ · +45
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| spegel-org/spegel | 3.8k | 3.8k |
45 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Caching with no configuration is the whole claim
The project is described in one line, and the name is part of it: Spegel means mirror in Swedish, and it is a stateless cluster local OCI registry mirror. Stateless is the word that does the work. There is no storage layer to operate and no garbage collection to schedule, because an image is not kept because an administrator put it there, it is kept because some node in the cluster already has it. The first feature listed says as much: locally cache images from external registries with no explicit configuration. So the deployment model is a pull-through behaviour shared across nodes rather than a registry someone seeds, and the trade is that nothing is guaranteed to be there until somebody has pulled it once.
Six benefits, all of them about pulling
The feature list is written as a list of problems rather than a list of capabilities, and every item is a pulling problem. Avoiding cluster failure during external registry downtime is the resilience argument. Improving image pull speed and pod startup time by pulling from the local cache first is the performance argument. Avoiding rate limiting when pulling from external registries, with Docker Hub given as the example, is the politeness argument. Decreasing egressing traffic outside the cluster's network is the cost argument, since egress is billed and throttled. Increasing image pull efficiency in edge node deployments is the topology argument. So the design target is a cluster with many nodes and a slow or shared uplink, and the phrase about home lab use in the note near the top of the file is not a throwaway remark.
The support note rules this out of a critical path
One note sits above the features and it is the most important sentence in the file. Spegel is described as a project with an evolving API and no guaranteed support, with assistance provided on a best effort basis by the developers, and with the focus stated as the home lab and the individual contributor use case. Read as a whole, that is a project optimised for a person who can read Go and change it when an API moves, rather than for a platform team that needs a compatibility promise. It also means the README is deliberately short, since the real documentation lives on a separate site: the only other content is a getting started guide link and an acknowledgement that the project was initially developed at a company, Xenit AB.
Discovery is a distributed hash table, not a registry index
The dependency list shows how the mirror knows what exists. There is a libp2p host library and a Kademlia distributed hash table implementation, so nodes find each other by content identifier rather than by asking a server. Content addressing comes from the ipfs content identifier package, with the multiformats libraries for addresses, codecs and hashes underneath it. Remote procedure calls go over gRPC, and a DNS library is present, which is the likely mechanism for resolving ordinary image references to the peers that hold them. The result is that a node asks the cluster which peers have a digest and pulls from one of them, and there is no central component that could become a single point of failure or need to be backed up.
containerd is a dependency, not an integration
Several direct requirements are containerd packages: the API, the second major version of the library itself, the error definitions, the platform detection helper and the type URL package, plus the OpenContainers image specification and the digest package. That combination is what a pull-through proxy needs in order to speak the same protocol as the runtime doing the pull, which is also why the project is Go rather than a shell wrapper around a registry. Two more dependencies tell you what the mirror does with traffic: a high dynamic range histogram library and the Prometheus client, which is the instrumentation for a component whose job is to answer many pulls quickly. A goroutine leak detector and a concurrency error group package are present too, which are the marks of a project that has fought with lifetime bugs.
The container claims a nonroot base and then becomes root
The image is five statements long, and one of them contradicts the base. It starts from the static distroless image in its nonroot variant, which contains no shell and no package manager, takes the target operating system and architecture as build arguments, copies the single compiled binary out of a build directory into the image root, sets the entrypoint to it, and then sets the user to root. So the runtime variant is selected by the base image tag while the effective user is overridden afterwards. Whether that is deliberate, because binding a socket sometimes needs privileges, or simply left over from an earlier revision, is not explained anywhere in the file. Anyone running this with a restrictive security context should check the user themselves rather than trusting the base image name.
Integration tests are split by runtime, with hard timeouts
The Makefile shows how the project is tested and it is more elaborate than the README suggests. Unit tests run across the whole module with the race detector enabled. Two integration suites exist and they are separated by environment: one targets containerd directly and runs with a fast integration strategy and a 200 second timeout, the other targets Kubernetes, depends on building the image first, receives the image reference as an environment variable, and allows 300 seconds. Both use a count of one and verbose output, so each run is a fresh deployment rather than a reuse. Linting is a single golangci-lint invocation across everything, with its configuration at the root, and coverage is uploaded according to a separate codecov configuration file.
Helm chart documentation is generated, and the newest tag is a release candidate
Two build systems sit side by side. The Go binary is packaged by goreleaser, and the Makefile build target runs it in snapshot mode, clean, single target, skipping the before hooks, which is a developer build rather than a release. The Helm chart under charts has its documentation generated: the target runs a helm-docs tool from inside the chart directory, reading the values file and a template to produce the chart README, so the documented values cannot drift from the shipped ones. Images for local testing are tagged with the short commit hash and pushed under the project's GitHub container registry namespace. The release history is pre-1.0 and includes a candidate: v0.7.3 on 2026-07-01, v0.7.4 on 2026-07-15 and v0.8.0-rc.1 on 2026-09-02, with the last push to the main branch dated 2026-10-01.
Editorial conclusion
Spegel suits a home lab or a small cluster where pulling from Docker Hub is slow, rate limited, or a single point of failure when the registry is down. It does not suit a production platform with a support contract, because the project states its API is evolving and support is best effort, and it is not a replacement for a garbage collecting registry such as Harbor or Kraken, since nothing is stored deliberately. Before deploying, read the getting started guide rather than the README, which is only a feature list, and check that your node can run a distroless binary that needs access to the container runtime socket.
Frequently asked questions
What is Spegel?
A stateless cluster local OCI registry mirror written in Go, where Spegel is the Swedish word for mirror. It caches images from external registries with no explicit configuration, so pulls come from a local copy first, which improves pull speed and pod startup and keeps a cluster working when an external registry is down or rate limiting.
Does Spegel store images like a normal registry?
No. It is described as stateless, and an image is present on a node because some node already pulled it. That is why the feature list emphasises caching with no explicit configuration rather than pre-seeding, and it is also why there is no retention policy to configure.
Can I rely on Spegel for production support?
The project states that it has an evolving API and no guaranteed support, that assistance is best effort from the developers, and that the focus is the home lab and individual contributors. Deployment instructions live in a getting started guide on the project documentation site rather than in the README.
How is Spegel tested?
Unit tests run with the race detector, and two integration suites exist: one targets containerd directly with a fast strategy and a 200 second timeout, the other targets Kubernetes, builds the image first, receives the image reference as an environment variable and allows 300 seconds. Linting is a single golangci-lint run.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/spegel-org-spegel)Star history chart for your README
[](https://hysenlabs.com/projects/spegel-org-spegel)Was this useful?