IPFS Private Network: How Swarm Keys Control Who Connects

An IPFS private network is a group of IPFS nodes that only connect to peers holding the same swarm key, a 32-byte secret stored in each node's swarm.key file. A node without that key can't open a connection, so it never sees your DHT records or blocks.

TL;DR:

• A swarm key is a pre-shared key (PSK). libp2p checks it while the connection opens, before any DHT lookup or Bitswap request can run.
• The swarm.key file has three lines: /key/swarm/psk/1.0.0/, an encoding line such as /base16/, and the 256-bit key.
• You set one up by copying the same key to every node, removing the public bootstrap peers, and adding your own.
• Kubo still lists private networks as experimental: TCP only, no QUIC, and every byte is encrypted twice.
• A private network decides who can connect. Pinning decides what stays stored, and encryption decides who can read a file. They are three separate controls.

Updated Oct 28, 2026: added the swarm.key file format, the Kubo setup commands, a connection diagram, the TCP-only limit, and a closing section on how AIOZ Pin fits.

What Is an IPFS Private Network?

A normal IPFS node joins one big public swarm, where any peer can dial any other peer and the public DHT tells everyone who provides which CID. That openness is what lets a stranger fetch your file by its CID alone.

A private network keeps the same IPFS software but closes the swarm: every member holds one shared secret, and libp2p refuses any connection where the other side can't prove it has the same secret. Your nodes still run a DHT, exchange blocks with Bitswap, and pin content, but they do all of it among themselves.

The libp2p spec for this feature states the guarantee plainly. Nodes of different private networks must not be able to connect to each other, and that includes a private node and a public one. The spec also notes the guarantee only holds while knowledge of the key stays limited to trusted parties.

What Is a Swarm Key?

A swarm key is a 256-bit (32-byte) pre-shared key that lives in a file named swarm.key inside your IPFS repo. The file starts with a path-style header: the first line names the format, /key/swarm/psk/1.0.0/, and the second names the encoding, which is /base16/, /base64/, or /bin/. The key itself comes last.

Here is what a base16 file looks like, generated with Python's secrets module on our own machine, so it is a real key in the right shape. Don't reuse it, because anyone reading this page now has it.

$ python3 -c "import secrets; print('/key/swarm/psk/1.0.0/\n/base16/\n' + secrets.token_hex(32))"
/key/swarm/psk/1.0.0/
/base16/
b214fdafa191033c95ab60e1b797796e466058fdaa1c760c3e7783b8668d9e83

The 64 hex characters are the 32 key bytes. The Kubo docs use a small Go tool, ipfs-swarm-key-gen, to write the same file. Both approaches give you a random 256-bit key, which is all the format asks for.

How Do You Set Up a Private IPFS Network?

The Kubo docs describe the whole setup in four moves. We have no IPFS binary on this machine, so the commands below are quoted from the Kubo docs and were not run here. Replace <multiaddr> with the address of a node inside your own network.

# 1. Generate a key once (Kubo docs use ipfs-swarm-key-gen)
go install github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen@latest
ipfs-swarm-key-gen > ~/.ipfs/swarm.key

# 2. Copy that same swarm.key into every member's repo ($IPFS_PATH if you use a custom one)

# 3. Stop dialing the public bootstrap peers, then add your own
ipfs bootstrap rm --all
ipfs bootstrap add <multiaddr>

# 4. Optional safety switch: refuse to start without a private network
export LIBP2P_FORCE_PNET=1

You need step 3 because the default bootstrap peers belong to the public network and your node can't connect to them once it has a key. Without your own bootstrap peer, a fresh node starts with nobody to talk to. Kubo's docs point out that a bootstrap node is just a normal node with a known address, so any always-on member can play that role.

With step 4 in place, a missing key file stops the daemon from starting, so a node can't slip into the public swarm by accident. Newer Kubo releases also fetch network settings through AutoConf. The Kubo config docs suggest the autoconf-off profile for private networks, so you control every endpoint yourself.

What the Swarm Key Does on the Wire

The PSK layer sits underneath the normal libp2p security handshake. When two nodes connect, each side sends a random 24-byte nonce. From then on, all traffic is XORed with an XSalsa20 stream built from the shared key and that nonce.

If the keys differ, the decrypted bytes are noise and the connection fails at the next step. The spec says the layer was designed to leak as little as possible: there is no recognizable handshake for an outsider to fingerprint.

After the PSK layer, libp2p runs its usual encrypted, authenticated channel on top. So traffic inside a private network is encrypted twice. The spec's authors chose XSalsa20 over AES-CTR for its 192-bit nonce, which makes a nonce collision very unlikely when many nodes share one key. Their benchmarks also showed it running about twice as fast as AES-CTR on the hardware they tested.

Limits to Know Before You Rely on It

Kubo's experimental-features page calls private networks "stable but not quite ready for prime-time". Here is what that means for you in practice.

• TCP only. The PSK layer does not work with QUIC, so a private node loses one of the transports Kubo enables by default. Our post on IPFS transports: TCP vs QUIC explains what you give up.
• Double encryption costs speed. The Kubo docs flag this overhead directly.
• One key for everyone. Every member holds the same secret. You can't revoke one member, so removing someone means making a new key and copying it to every other node.
• Members see everything. The key controls who joins. Once a peer is inside, it can request any CID the network provides.

Private Network vs Pinning vs Encryption

People often mix up three controls that answer three different questions. A private network answers "who can connect to my nodes?" Pinning answers "which content stays stored instead of being garbage collected?" Encryption answers "who can read this file if they get the bytes?"

Pinning a file never makes it private. On the public network, pinning makes the file easier for anyone to fetch, which is the opposite of what a swarm key does. Our guide to unpinning and garbage collection covers what pinning does.

A private network also isn't file encryption. Data sits unencrypted in each member's blockstore, and every member can read it. If you need files that stay unreadable even to peers who hold the CID, encrypt them before you add them. Does IPFS encrypt your files? walks through that choice.

How AIOZ Pin Handles It

AIOZ Pin works on the public IPFS network. Our gateway docs say that content you pin with AIOZ Pin "becomes available on the public IPFS network". They add that anyone running an IPFS node can access it through their own node. That is the point of a pinning service: your CID stays reachable for whoever needs it, through any IPFS node or through our public and premium gateways.

So AIOZ Pin can't join a private swarm, and our docs don't describe swarm keys. If you run a private network, your own members pin content for each other. If you want public reach but private contents, encrypt the file first and pin the ciphertext. The call is the same documented upload you would use for any file (not run here, no credentials on this machine):

curl --location --request POST 'https://api.aiozpin.network/api/pinning/' \
  --header 'pinning_api_key: KEY' \
  --header 'pinning_secret_key: SECRET' \
  --form 'file=@"/encrypted-report.bin"'

Content already on the public network can also be pinned by its CID alone, without a re-upload. Our guide on pinning by CID shows that route. For the full upload reference, see the AIOZ Pin pinning API docs.

Frequently Asked Questions

What is an IPFS private network? A set of IPFS nodes that share one swarm key, so each node only connects to peers holding that key and outsiders can't join, query the DHT, or fetch blocks.

Where does the swarm.key file go? In the root of your IPFS repo, which is ~/.ipfs by default or the folder set in $IPFS_PATH.

Can a private network use the default bootstrap peers? No. Those peers are on the public network and can't connect to you, so run ipfs bootstrap rm --all and add bootstrap peers from inside your own network.

Does a private IPFS network work over QUIC? Not today. The Kubo docs say the PSK layer is limited to TCP and does not work with QUIC.

Does a swarm key encrypt my stored files? No. It encrypts traffic between members, while files sit unencrypted in each member's blockstore, and every member can read them.

Can AIOZ Pin pin content inside a private network? No. AIOZ Pin pins to the public IPFS network, so for private contents with public reach, encrypt the file before you pin it.

Related Reading

• libp2p: The Networking Layer Underneath IPFS - the connection layer a swarm key gates
• How IPFS Finds and Retrieves Files: DHT and Bitswap - the lookups that stay inside a private network
• Types of IPFS Nodes: The Different Roles, Explained - including the bootstrap role you have to replace
• IPFS Transports: TCP vs. QUIC Explained - why TCP-only is a real cost
• Does IPFS Encrypt Your Files? Privacy on IPFS Explained - content privacy, which a swarm key does not give you

References

• Kubo docs: Experimental Features, Private Networks
• libp2p specs: Pre-shared Key Based Private Networks
• Kubo docs: Configuration reference (AutoConf, profiles)
• AIOZ Pin docs: Understanding Gateways and their Importance in IPFS