# uber/kraken: a P2P Docker registry for clusters that pull the same images

> Kraken is Uber's P2P distribution layer for Docker images, in production since 2018. It replaces the thundering herd on a central registry with a tracker-orchestrated peer graph, and it assumes you already have blob storage.

**uber/kraken** — P2P Docker registry capable of distributing TBs of data in seconds

- Repository: https://github.com/uber/kraken
- Stars: 6,751 · Forks: 488
- Language: Go
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/uber-kraken

## The problem Kraken solves: many hosts, the same large image, one registry

A conventional Docker registry serves every pull from its own network interface. When a fleet of nodes rolls out at once, they all request the same layers, and the registry's uplink becomes the bottleneck. Kraken's answer is to stop treating the registry as the source of bytes and treat it as the source of truth about which bytes exist.

The project is aimed at operators of large, hybrid cloud clusters. The README states Kraken has been in production at Uber since early 2018, and that in its busiest cluster it distributes more than 1 million blobs per day, including 100k blobs of 1G or more. Those are the project's own figures, not an independent measurement. The intended reader is someone who already runs a registry and wants a distribution layer in front of it, not someone who wants a registry to exist at all.

The design target is stated plainly: support at least 15k hosts per cluster, and keep download speed largely independent of blob size and cluster size. If your cluster is a dozen nodes pulling a 200MB image, none of this applies to you.

## Tracker, origin, agent, proxy: how a blob actually moves

Kraken splits into four services, and the split is the interesting part. The agent runs on every host and implements the Docker registry interface, so a node pulls from localhost and never talks to a central registry for layer bytes. The agent announces what content it holds to the tracker and connects to peers the tracker returns.

The tracker does not move data. It tracks which peers have which content, both in progress and completed, and hands back an ordered list of peers to connect to for a given blob. The README describes the resulting topology as a pseudo-random regular graph, chosen because it has high connectivity and a small diameter. With one seeder and thousands of peers joining in the same second, the design targets a minimum of 80 percent of max upload and download speed in theory, 60 percent with the current implementation.

Origins are the dedicated seeders. They store blobs as files on disk backed by pluggable storage such as S3, GCS or ECR, and they form a self-healing hash ring to spread load. The proxy also speaks the Docker registry interface: it uploads each image layer to the origin responsible for it on the ring, and uploads tags to the build-index. The build-index maps a human-readable tag to a blob digest, stores tags as files on disk over the same pluggable storage, and powers cross-cluster replication through duplicated queues with retry.

The README is explicit that the build-index offers no consistency guarantees and that clients should use unique tags. That is a real constraint, not a footnote: if your workflow repushes the same tag and expects the new digest to be visible immediately everywhere, this component is not built for that.

## Installing Kraken and running the devcluster

The README gives two paths. All Kraken components ship as Docker containers, and the Makefile builds those images:

```bash
make images
```

For configuration details the README points at docs/CONFIGURATION.md rather than inlining them. The faster way to see the system work is the devcluster target, which starts a herd container holding origin, tracker, build-index and proxy, plus two agent containers, all with development configuration:

```bash
make devcluster
```

The README notes that Docker-for-Mac is required to make the devcluster work on a laptop, and points at examples/devcluster/README.md for more. Expect four services and two agents in your container list once it comes up.

For Kubernetes there is an example Helm chart that deploys Kraken with an example HTTP fileserver backend:

```bash
helm install --name=kraken-demo ./helm
```

After that install, the README states every node exposes a Docker registry API on localhost:30081, and it points to examples/k8s/demo.json for a pod spec that pulls from the Kraken agent. Read examples/k8s/README.md before adapting the chart; the chart is described as an example, and the HTTP fileserver backend is a demo storage option rather than the S3 or GCS setup a production cluster would use.

## Where Kraken is the wrong tool

Kraken deliberately does not manage data. It plugs into blob storage you already operate, and the storage interface is the one place where a new backend has to be written. If you have nowhere to put blobs, Kraken is not a registry you can stand up on its own; you need S3, GCS, ECR, HDFS or another registry underneath it first.

The build-index weakness is the second boundary. Tags are stored as files on disk, and the README states there are no consistency guarantees, with the advice that the client should use unique tags. Teams whose release process mutates tags in place, or whose tooling reads a tag immediately after a push and expects the new digest, will fight this.

The third boundary is sizing. The README says Kraken supports arbitrarily large blobs and layers, but adds that the project normally limits max size to 20G for the best performance. The headline performance numbers also come from a specific configuration: a 3G image with 2 layers pulled by 2600 hosts concurrently, 5200 blob downloads, a 300MB/s speed limit on all agents, 5 trackers and 5 origins, giving p50 of 10s, p99 of 18s and p99.9 of 22s. That is a benchmark from the project, and it says nothing about how the system behaves with a single tracker or with small images where the coordination overhead may not pay for itself.

Finally, the agent runs on every host. That is a deployment commitment across the whole fleet, not a sidecar you add to one namespace.

## Kraken compared with Dragonfly and plain BitTorrent

The README compares Kraken directly with Alibaba's Dragonfly. Dragonfly uses one or a few supernodes that coordinate the transfer of every 4MB chunk in the cluster. Kraken's argument is that this central coordination caps cluster throughput at the processing power of those hosts and degrades linearly as blob size or cluster size grows, because every chunk decision passes through them.

Kraken's tracker only helps build the connection graph and leaves the negotiation of the actual transfer to individual peers. The README claims this scales better with large blobs, and adds that Kraken is highly available and supports cross-cluster replication, both of which it says a reliable hybrid cloud setup requires. Whether the first claim holds in your environment depends on your blob sizes; the second is a design property you can check in the architecture, since no component is described as a single point of failure.

The BitTorrent comparison is more interesting because Kraken started there. The README states Kraken was initially built with a BitTorrent driver, and that the team ended up implementing its own P2P driver based on the BitTorrent protocol to get tighter integration with storage solutions and more control over performance optimizations. The stated goal differs from BitTorrent's: Kraken optimizes for global max download time and communication overhead in a stable environment, not for the open, adversarial swarm BitTorrent assumes. If you want a general-purpose torrent client, this is not that, despite the bittorrent topic on the repository.

## Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-21, one day before this writing. Recent releases are v0.1.29 on 2026-09-14, v0.1.28 on 2026-08-31 and v0.1.27 on 2026-07-06. The version numbers have stayed in the 0.1.x line, so despite years in production at Uber, the project does not present a 1.0 API stability promise. Upgrades should be treated as upgrades of a pre-1.0 system.

The module targets Go 1.24.0, and the Makefile defaults GOLANG_IMAGE to golang:1.24.0. The Makefile also documents a real cross-compilation constraint: cross compiling cgo for sqlite3 is not well supported on macOS, so binaries that use cgo are built inside a Linux container via a docker run invocation, while tools that do not use cgo can be built natively. That container-based build path is part of the development loop, not an optional extra.

Kraken is licensed Apache-2.0. That is a permissive licence with an explicit patent grant, and it is the same family most Go infrastructure projects use. It does not remove the operational cost of running four services plus an agent on every host, and it says nothing about the licence of the blob storage backend you plug in. Check the terms of that backend separately; this is a description of the licence file in the repository, not legal advice.

## Conclusion

Adopt Kraken if you run a large cluster where hundreds of nodes pull the same multi-gigabyte images and you already have S3, GCS, ECR or HDFS to back it. Do not adopt it as a standalone registry for a small team, and do not expect the tag index to behave like a normal registry. Before committing, verify three things: that your cluster can host the agent on every node, that you are comfortable with the build-index having no consistency guarantees, and that your blob sizes stay near the 20G ceiling the README recommends.

## FAQ

### What is uber/kraken?

It is a P2P-powered Docker registry distribution layer built in Go. The README describes it as designed for Docker image management, replication and distribution in a hybrid cloud environment, with pluggable backend support so it can sit in front of an existing registry as the distribution layer.

### Does uber/kraken store my image data itself?

No. The README states Kraken plugs into reliable blob storage options such as S3, GCS, ECR, HDFS or another registry instead of managing data, and that the storage interface is simple and new options are easy to add.

### How do I try uber/kraken locally?

The README's devcluster target starts a herd container with origin, tracker, build-index and proxy plus two agent containers using development configuration. It notes Docker-for-Mac is required to make the devcluster work on a laptop.

### Does uber/kraken guarantee that a tag points to the newest digest?

The README says the build-index has no consistency guarantees and advises that the client should use unique tags. Repushing an existing tag and expecting immediate visibility across the cluster is outside what the component promises.

## Sources

- [Issues](https://github.com/uber/kraken/issues)
- [License: Apache-2.0](https://github.com/uber/kraken/blob/master/LICENSE)
- [README](https://github.com/uber/kraken/blob/master/README.md)
- [Releases](https://github.com/uber/kraken/releases)
- [uber/kraken on GitHub](https://github.com/uber/kraken)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/uber-kraken