IPFS Cluster Pinning Explained (2026)
Running a single IPFS node is great for experimentation, but when you need real scalability, high availability, and reliable data durability, IPFS Cluster becomes essential. IPFS Cluster is a separate but complementary tool that allows you to coordinate pinning across multiple IPFS nodes using consensus.
Why Use IPFS Cluster for Pinning?
Coordinated Pinning
IPFS Cluster ensures that when you pin content, it gets replicated across multiple nodes according to your replication factor. No more manually pinning the same CID on every node.
High Availability
If one node goes down, your content remains available and pinned on the remaining healthy nodes. The cluster automatically handles rebalancing when nodes come back online.
Consensus & Consistency
Uses CRDT (Conflict-free Replicated Data Type) or Raft consensus so all nodes agree on the current state of pins. This prevents split-brain situations common in naive multi-node setups.
Horizontal Scalability
You can easily add more IPFS nodes to the cluster as your storage or traffic grows. Pinning operations are distributed, making it suitable for production workloads.
Flexible Allocation
Supports different allocation strategies — you can pin to all nodes, specific nodes, or use custom allocation logic. Useful for geo-distribution or performance optimization.
Easy Integration
Comes with a clean REST API. You can control the entire cluster from Node.js, TypeScript, or any other language without needing to run IPFS Cluster logic inside your application.
How IPFS Cluster Pinning Works
Architecture
IPFS Cluster runs as a separate service alongside your IPFS nodes. Each cluster peer communicates with its local IPFS daemon. The cluster layer handles consensus and coordination, while the actual data storage and retrieval still happens through IPFS.
CRDT vs Raft
Modern IPFS Cluster defaults to **CRDT** consensus (since 2023–2024), which is eventually consistent and works well in unreliable networks. Raft is still available for stronger consistency when needed.
Pin Lifecycle
When you submit a pin request to the cluster:
1. The request is replicated via consensus
2. Each node decides whether to pin based on allocation rules
3. The cluster tracks pin status across all peers
4. Failed pins can be retried or reported
Monitoring & Management
IPFS Cluster exposes metrics and status via its API. You can monitor pin status, replication health, and node availability. Many people combine it with Prometheus + Grafana for production observability.
Docker Compose Deployment Example
Here’s a practical **3-node IPFS Cluster** setup using Docker Compose. This is a common starting point for self-hosters who want high availability and coordinated pinning.
version: '3.8'
services:
ipfs0:
image: ipfs/kubo:latest
container_name: ipfs0
volumes:
- ipfs0-data:/data/ipfs
ports:
- "4001:4001" # Swarm
- "5001:5001" # API
- "8080:8080" # Gateway
environment:
- IPFS_PATH=/data/ipfs
cluster0:
image: ipfs/ipfs-cluster:latest
container_name: cluster0
depends_on:
- ipfs0
environment:
- CLUSTER_PEERNAME=cluster0
- CLUSTER_SECRET=your-very-long-secret-here
- CLUSTER_IPFSHTTP_NODEMULTIADDRESS=/dns4/ipfs0/tcp/5001
- CLUSTER_CRDT_TRUSTEDPEERS=*
volumes:
- cluster0-data:/data/ipfs-cluster
ports:
- "9094:9094" # REST API
- "9096:9096" # Cluster Swarm
# Repeat similar blocks for ipfs1 + cluster1 and ipfs2 + cluster2
# (change container names, volumes, and peer names accordingly)
volumes:
ipfs0-data:
cluster0-data:
Quick Notes on the Example
• Use a strong random value for CLUSTER_SECRET (generate with openssl rand -hex 32)
• All cluster peers must use the **same secret**
• You can expand this to 5+ nodes for better redundancy
• Expose port 9094 only internally or behind authentication in production
• Use ipfs-cluster-ctl or the REST API to manage pins after deployment
Using IPFS Cluster from Node.js & TypeScript
Recommended Approach
Most production setups interact with IPFS Cluster through its **REST API** rather than embedding cluster logic in the application. This keeps your Node.js/TypeScript services clean and focused.
Common Libraries
You can use the official HTTP client or simple `fetch`/`axios` calls. TypeScript has good support for the IPFS Cluster API, making it easy to work with CIDs and pin operations safely.
When Should You Use IPFS Cluster?
Use IPFS Cluster when you need:
Production-grade pinning with high availability, automatic replication across multiple nodes, or when running multiple IPFS nodes and want coordinated management.
Single node may be enough when:
You’re just experimenting or running low-traffic personal projects. For anything serious, IPFS Cluster is strongly recommended.
Self-Hosting IPFS Cluster
Deployment
IPFS Cluster is commonly deployed using Docker Compose (as shown above) or Kubernetes. Most people start with 3 nodes for good redundancy.
Production Tips
Use persistent volumes, set up monitoring, and consider running private cluster nodes + public gateways for external access.
Official Resources
Questions for the Community
Are you currently using IPFS Cluster in production or for personal projects?
What replication factor and consensus mode are you running?
How are you monitoring pin health and cluster status?
Disclaimer
This content is for educational and informational purposes only. It is not technical advice. Operating distributed systems like IPFS Cluster requires understanding of consensus, networking, and operational overhead. Always test thoroughly in non-production environments first.
