
Multi-node pinning replicates content by pinning the same CID on several IPFS nodes and tracking how many copies exist. IPFS Cluster, the open-source tool built for this, sets a minimum and a maximum replication factor for each pin and decides which peers hold the copies.
TL;DR:
replication_factor_min, below which Cluster re-allocates the pin, and replication_factor_max, the number of peers it tries to useUpdated Oct 29, 2026: rewrote the post around IPFS Cluster, with its components, consensus options, pin ls vs status checks and Pinning Service API support, and added a labelled diagram and a closing section on what the AIOZ Pin docs say.
On a single Kubo node, a pin answers one question per CID: is it protected from garbage collection here or not. That is enough for your own machine, and the post on what unpinning and garbage collection do covers that model in full.
A pinning service holding many customers' files across many machines has to answer harder questions for every pin. How many copies should exist? Which nodes should hold them? And what should happen when one of those nodes goes offline? None of these questions exist on one node, so you need a coordination layer on top.
IPFS Cluster is the open-source pinset orchestration tool for IPFS, and its docs describe in detail how multi-node pinning works. It ships as three programs. ipfs-cluster-service runs a cluster peer, ipfs-cluster-ctl sends it commands, and ipfs-cluster-follow runs a follower peer.
A cluster peer doesn't store blocks itself. It talks to an IPFS daemon over that daemon's HTTP API on localhost:5001, so you run Kubo separately on every machine. When you pin something, the cluster peers ask their own Kubo daemons to pin it.
The cluster peers form their own isolated libp2p network, secured by a shared cluster_secret. That network is separate from the public IPFS network, which also means cluster peers handle NAT traversal and ports on their own. It works much like the private IPFS networks that swarm keys create, built on the same libp2p networking layer.

Every pin you submit to IPFS Cluster carries two options. replication_factor_min is the minimum number of copies the pin should have in the cluster. replication_factor_max is how many peers Cluster tries to allocate. If you don't set them, the defaults from the cluster configuration apply.
On submission, Cluster tries to allocate up to the maximum but doesn't fail as long as it finds more than the minimum. If it can't reach the minimum, the pin fails right away. Later, if allocated peers become unavailable and the count drops below the minimum, automatic repinning moves the pin to new peers.
Pins that sit between the two numbers are left alone by automatic repinning. That gap matters, and the docs recommend some leeway, usually 2-3 or 3-5. Without it, a peer that drops out for a few seconds could trigger repinning and leave the cluster unbalanced, even if the peer comes back with the data intact.
The IPFS Cluster pinning guide shows what this looks like from the command line. The commands and output below are quoted from that guide and were not run here:
# Not run: quoted from the IPFS Cluster "Adding and pinning" guide
$ ipfs-cluster-ctl pin add --name cluster-website --replication 3 /ipns/ipfscluster.io
QmXvQLhK2heNz65fWRabTfbzXwYfaBgEBuTdUJNzp69Xjx :
> cluster2 : PINNED | 2021-12-07T15:24:58Z | Attempts: 0 | Priority: false
> cluster3 : PINNING | 2021-12-07T15:24:58Z | Attempts: 0 | Priority: true
> cluster0 : PINNING | 2021-12-07T15:24:58Z | Attempts: 0 | Priority: true
> Qmabc123 : REMOTE | 2021-12-07T16:25:07.48933158+01:00 | Attempts: 0 | Priority: false
> Qmabc456 : REMOTE | 2021-12-07T16:25:07.4893358+01:00 | Attempts: 0 | Priority: false
Three peers pin or are pinning the content, and the two peers marked REMOTE are cluster members that were not allocated this pin.
A replication factor tells Cluster how many peers to use, not which ones. The allocation process builds a priority list of peers and takes up to replication_factor_max from it. The order comes from the metrics each peer broadcasts and from the allocator's allocate_by setting.
With allocate_by set to ["freespace"], the peers with the most free space win. With ["tag:region", "freespace"], Cluster groups peers by region and spreads copies across regions, taking the peer with the most free space in each. Only peers with recent, unexpired metrics count as candidates.
Existing allocations are sticky. Cluster keeps them unless the allocated peers become unavailable and the pin falls below its minimum, and changing the replication factor also respects the peers already chosen. If you name peers by hand, those peers get priority as long as they are available.
A pin moves through two stages. In the cluster-pinning stage, Cluster runs allocation, builds a pin object with the chosen peers, and commits it to the shared pinset. The docs count pin add as successful once this stage finishes, because it is fast.
In the IPFS-pinning stage, each allocated peer queues the CID and asks its own Kubo daemon to run ipfs pin add. This is the slow part, since it moves real data, so it runs asynchronously. A pin that fails goes into an error state and gets retried later, with an attempt counter.
Peers keep two queues: a priority queue for new pins and pins that haven't failed many times, and a second queue for the rest. That way, a few stuck pins can't block your new ones. If you want pin add to wait for real storage, the --wait flag returns once at least one peer has finished the IPFS-pinning stage.
Every peer keeps a copy of the global pinset, and a consensus component keeps those copies in step. You choose it when you initialize a peer, with --consensus crdt or --consensus raft.
CRDT is the default. It publishes pinset updates over GossipSub, stores them as an append-only Merkle-CRDT DAG, and reaches eventual consistency without a leader. Only peers listed in trusted_peers can change the pinset. Raft, the other option, sends updates directly to every peer, and the docs now call it legacy.
IPFS Cluster also supports collaborative clusters. Untrusted peers can join as followers that pin the shared pinset without permission to edit it, so a community can help keep a public dataset online.
IPFS Cluster gives you two views, and mixing them up is a common mistake. ipfs-cluster-ctl pin ls reads the shared pinset, which every peer has. It shows each pin's replication factors and allocations, so it tells you what should happen.
ipfs-cluster-ctl status contacts every allocated peer and asks for its real state: PINNED, PINNING, PIN_ERROR or UNEXPECTEDLY_UNPINNED. That tells you what did happen, but the docs warn it can be very expensive on clusters with many peers. Pins in error get retried by ipfs-cluster-ctl recover, which every peer also runs on a timer.
The same status ideas show up in the IPFS Pinning Service API, and IPFS Cluster includes an experimental implementation of it. Its docs list the caveats: the request ID is the CID, the same CID can't be tracked once per user, and pagination isn't supported. If a pin you created stays in a waiting state, what each pin status means walks through the causes.
The AIOZ Pin docs describe pinning as keeping your files persistently available within the IPFS network, as the top layer of the AIOZ DePIN. They also describe smart caching that replicates frequently accessed content within the DePIN to speed up retrieval. The docs don't publish a replication factor or a copy count, and they don't say whether IPFS Cluster or other software coordinates the nodes.
What you control is the request. Pinning an existing CID takes a hash_to_pin and optional metadata, with no field for copies or regions. This request is copied from the API reference and was not run here, since it needs real keys:
# Not run: from the AIOZ Pin Pinning API reference (Pin by CID)
curl --location --request POST 'https://api.aiozpin.network/api/pinning/pinByHash' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{"hash_to_pin": "<CID>", "metadata": {"name": "my-file"}}'
The response includes a pinned flag and a status field, and pinning existing content by CID covers the workflow. Next step: read the AIOZ Pin Pinning API reference.
What is IPFS Cluster used for? It orchestrates one pinset across many IPFS nodes. It decides how many copies each CID gets and which peers hold them, and it re-allocates pins when peers drop out.
What is a replication factor in IPFS Cluster? Two numbers per pin. The minimum is the copy count below which Cluster re-allocates, and the maximum is how many peers it tries to allocate.
Does IPFS Cluster replace Kubo? No. Each cluster peer runs next to an IPFS daemon and controls it over the daemon's HTTP API, so you still run Kubo on every machine.
Should I use CRDT or Raft consensus? The IPFS Cluster docs make CRDT the default and call Raft legacy, noting it may not behave well with very large pinsets.
Why does pin ls show a pin that status reports as an error? pin ls shows the shared pinset, meaning what should be pinned. status asks each allocated peer what it holds, so a gap between them means the IPFS-pinning stage failed on some peer.
How many copies does AIOZ Pin keep? The AIOZ Pin docs don't publish a copy count. They describe persistent pinning and smart caching that replicates frequently accessed content within the AIOZ DePIN.

A multiaddr is a network address that names every protocol it uses, like /ip4/.../tcp/4001/p2p/ and a peer ID. Learn to read one and how IPFS peer IDs work.

IPFS bootstrap nodes are the first peers a new node dials to join the Amino DHT. See how Kubo uses them, who runs them after Shipyard, and how to edit the list.

The ipfs.io gateway now returns HTTP 429 to scripts and servers and sends browsers to inbrowser.link. See who runs the public IPFS services and what to change.

An IPFS glossary of 115 terms from A to Z: CIDs, Bitswap, the DHT, IPNS, gateways and pinning, each defined in plain words and linked to a deeper guide.

IPFS Provide Sweep is Kubo's provider that batches CIDs by DHT region, not one lookup each. See how it works, when it became default, and how to check it.

An IPFS dedicated gateway on AIOZ Pin is called a premium gateway. See what the free plan limits, what a paid plan adds, and what happens at zero balance.