IPFS Cluster: coordinating replicated pins across peers

Why IPFS Cluster sits beside Kubo

IPFS Cluster solves a coordination problem that appears when content must remain pinned across several IPFS daemons. A single Kubo daemon can pin content on its own, but the README describes IPFS Cluster as the layer that allocates, replicates and tracks a global pinset across a swarm. Its intended users are therefore operators distributing IPFS infrastructure among multiple peers, rather than developers looking for another IPFS implementation. The service is written in Go and is designed to run alongside `kubo`, also identified as `go-ipfs`, as a sidecar.

The project separates responsibilities into three applications. `ipfs-cluster-service` participates in the cluster beside a Kubo daemon. `ipfs-cluster-ctl` communicates with a cluster peer's HTTP API and is the normal administrative client. `ipfs-cluster-follow` provides a specialized peer role intended to simplify configuration and operation for follower peers. This is more than a command-line wrapper around Kubo. The service maintains a cluster-level view of pinned CIDs and coordinates decisions about their placement, while Kubo remains responsible for the underlying IPFS daemon role.

That distinction matters operationally. Adopting IPFS Cluster means introducing another long-running service, its API, its state and potentially a consensus mechanism. A deployment that only needs one daemon and a local pin command has no reason to absorb that coordination layer. IPFS Cluster becomes relevant when the desired property is a global pin policy across independently addressed peers.

How allocation, tracking and CRDT consensus fit together

The visible architecture divides cluster behavior into packages such as `allocator`, `consensus`, `state`, `pintracker`, `ipfsconn` and `peer_manager_test.go`. This layout supports a practical model in which peers exchange cluster decisions, track pins associated with Kubo instances and query or update cluster state through APIs. The repository description names allocation, replication and tracking as the core jobs. The README does not document each allocation strategy or explain how replication counts are configured, so those details cannot be reduced to a single universal procedure.

The example `docker-compose.yml` identifies CRDT as its consensus component. It creates three cluster peers, each attached to a corresponding Kubo container, and says that the cluster peers discover one another through mDNS on the Docker internal network. The first startup creates default configuration and places configurations and states in a host-side `compose` directory. That persistence arrangement is important because cluster coordination is stateful rather than a stateless request proxy.

The Docker image makes the deployment boundaries visible. It contains all three binaries, defaults `IPFS_CLUSTER_CONSENSUS` to `crdt`, stores data under `/data/ipfs-cluster`, and exposes ports `9094`, `9095` and `9096`. The example Compose file says that the cluster0 API port is exposed to localhost, although its environment block does not show the complete port mapping. The documented client command is still specific: `ipfs-cluster-ctl peers ls` should display all three peers a few seconds after startup.

Installing the service and control applications

The README directs users to `https://ipfscluster.io/download` for installation methods, including installation from source. It does not reproduce package-manager commands or a complete source installation tutorial, so this review does not invent one. For a source checkout, the repository Makefile exposes an `install` target that delegates to the Makefiles for all three command directories. The following command is copied from the repository root Makefile:

make install

That target covers `ipfs-cluster-service`, `ipfs-cluster-ctl` and `ipfs-cluster-follow`. The Makefile also has a `build` target, which delegates to the three application builds without installing them. If the objective is to produce local binaries first, the documented repository target is:

make build

The README points to separate reference documentation for each binary rather than claiming that these two commands configure an operating cluster. Initial peer identity, the cluster secret, Kubo connectivity, consensus selection and persistence still belong to the configuration process. Docker users can instead build the repository's runtime image with the command below, also copied from the Makefile:

docker build -t cluster-image -f Dockerfile .

The Dockerfile uses Go to build the binaries and Alpine for the runtime image. It does not describe `make install` as a replacement for environment-specific configuration.

Starting the three-peer Compose example and checking membership

The repository labels `docker-compose.yml` as a quick test environment for multiple peers. The file does not print a Compose startup command, so readers should use the deployment method documented by their Compose installation rather than receiving an invented `docker compose` variant. Once the example is started according to its own comments, the first useful check is peer discovery. The Compose file gives this exact client command:

ipfs-cluster-ctl peers ls

The expected result, according to the file, is a list of all three peers after startup. A shell session inside cluster0 is another documented path. The Compose comments use the following form for interactive execution:

docker exec -ti cluster0 sh

From that shell, the user can invoke `ipfs-cluster-ctl`, including the membership command above. Before starting, set `CLUSTER_SECRET` because the Compose environment references it as `${CLUSTER_SECRET}`. The file also assigns `CLUSTER_PEERNAME` to identify each cluster container. Those settings belong to the example deployment; they do not establish a production secret-management design.

The first verification should focus on connectivity and discovery, not on assuming that content has already been replicated. The README gives no first `pin add` command, CID, API request or replication policy. It also does not document how to export cluster0's API port in the incomplete environment configuration. Those omissions make the Compose file suitable as a topology reference, but incomplete as a standalone production guide.

Persistence, upgrades and operational boundaries

IPFS Cluster carries persistent state because peers must track cluster decisions and pin status. In the Compose example, configurations and states are stored under `compose/cluster0`, `compose/cluster1` and similar peer directories. The runtime image declares `/data/ipfs-cluster` as a volume and as `IPFS_CLUSTER_PATH`. A container restart that does not preserve the relevant volume can therefore conflict with the assumptions of a stateful cluster service, although the README does not provide a recovery procedure.

Upgrade planning also involves multiple moving parts. The service must connect to a compatible Kubo setup, while peers must agree on cluster state. Recent releases include `v1.1.6` dated 2026-05-11, `v1.1.5` dated 2025-12-17 and `v1.1.4` dated 2025-05-16. The repository is not archived, and the last push was on 2026-08-30. Those facts support continued repository activity, but they do not establish upgrade compatibility between Kubo, the cluster service and persistent state.

The release process has a repository entry named `RELEASE.md`, which the README identifies as the guide for maintainers cutting a new version. The README does not describe rolling upgrades, peer replacement, consensus migration, rollback or backup restoration. An adopter therefore needs answers to those questions in the linked user documentation before treating a version jump as routine. The example's persistent directories are a storage location, not a documented backup strategy.

The README describes dual licensing under Apache 2.0 and MIT terms, while the repository also contains `LICENSE`, `LICENSE-APACHE` and `LICENSE-MIT`. Its image metadata says `MIT+APACHE_2.0`. Organizations should inspect those files for their own compliance process, but this review does not provide legal interpretation.

Direct Kubo operation versus cluster-wide pin coordination

The clearest alternative is operating Kubo daemons directly and managing each daemon's pins without IPFS Cluster. That approach has fewer components: there is no `ipfs-cluster-service`, cluster HTTP API, `ipfs-cluster-ctl` control plane, peer discovery layer or distributed consensus state to operate. It is easier to reason about when each daemon is operated independently and a global pinset is not required.

IPFS Cluster takes a different approach. Instead of treating each Kubo instance as the complete administrative boundary, it coordinates a cluster view and distributes pin-related decisions among peers. The Compose example adds one Kubo container and one cluster peer for each of three positions. This extra machinery buys shared allocation and tracking, but it also creates operational questions about secret distribution, consensus, discovery, persistent state and coordination failures.

There are other repository choices worth separating from the product decision. `go.mod` includes Hashicorp Raft, Badger, Pebble, CRDT and libp2p-related dependencies, while the runtime example selects CRDT. Those components indicate several technical building blocks, but the README does not provide enough detail to recommend a consensus backend or datastore for a particular deployment. The choice between direct Kubo management and IPFS Cluster should therefore be driven first by whether shared pins across peers are required, not by the number of Go packages in the repository.

Editorial conclusion

IPFS Cluster is appropriate for operators already running multiple Kubo daemons and requiring a coordinated global pinset. It is the wrong choice for a single daemon or for teams that cannot operate consensus and persistent cluster state. Verify first that Kubo networking and persistence are configured correctly, then inspect `docker-compose.yml` for the exact peer layout and exposed API port before adopting the example deployment.

Frequently asked questions

Official sources

1. ipfs-cluster/ipfs-cluster on GitHub
2. Issues
3. Project website
4. README
5. Releases