IPFS Integration with Tor Hidden Services: 2026 Guide

IPFS identifies content by its hash (CID - Content Identifier) rather than location. A file on IPFS has the same CID regardless of which server hosts it. This has implications for .onion services: files added to IPFS are retrievable by any IPFS node that has them, regardless of the originating hidden service. The CID is permanent and globally resolvable. Use cases: a hidden service publishes documents to IPFS and provides the CIDs via their .onion interface - documents are retrievable from IPFS even if the .onion goes down, distributing large files (video, audio, large archives) via IPFS reduces bandwidth requirements on the hidden service server (other IPFS nodes serve the content), and providing permanent links to content that outlive the hidden service's operational lifespan.

IPFS daemon can be configured to use Tor as a transport. This routes IPFS's peer connections through Tor, hiding the IPFS node's IP. Configuration: in the IPFS config file (~/.ipfs/config): set Swarm.Transports.Protocols to prefer onion addresses, configure the IPFS HTTP API to listen on localhost only. IPFS over Tor has limitations: performance is significantly lower (IPFS is P2P and highly connected; routing through Tor adds significant latency and reduces peer count), and IPFS's peer discovery may not work well over Tor (many peers are IP-reachable, not .onion-reachable). Practical approach: run IPFS for content addressing and distribution, but accept that the IPFS daemon itself may reveal network information. Use Tor only for the .onion service interface, not necessarily for all IPFS peer connections.

Public IPFS exposes your content to the global network. A private IPFS network (swarm key) restricts peers to those with the matching swarm key. Setup: generate a swarm key (ipfs-swarm-key-gen > ~/.ipfs/swarm.key), distribute the same key to all nodes in your private network, set LIBP2P_FORCE_PNET=1 to enforce the private network. Private IPFS network use cases: a hidden service and its backup servers share a private IPFS network for resilient content distribution between known nodes, an organization distributes internal documents via private IPFS accessible only to nodes with the swarm key, and content is IPFS-distributed within the private network while the .onion service provides the access interface to users.

IPFS content is available as long as at least one node pins it. Pinning explicitly marks content to keep. For hidden service long-term archival: pin important content on multiple nodes (the hidden service server, a backup server, and optionally a pinning service). Pinning services: Pinata, Web3.Storage, Filebase - commercial services that pin IPFS content to ensure availability. Privacy consideration: public pinning services pin content to the public IPFS network, making it discoverable. For sensitive content, use private pinning (pin on your own nodes only) or a private IPFS network. MFS (Mutable File System): IPFS has an MFS that provides a Unix-like directory interface. Files in MFS are pinned by default. Use MFS for organizing content on your hidden service's IPFS node.

Architecture for combining .onion and IPFS: the hidden service serves dynamic content (user authentication, personalized pages, forms) directly from the application server, and static content (files, documents, images, media) is stored on IPFS and referenced by CID in the application database. Frontend: the .onion interface provides a UI that shows IPFS CIDs for downloadable content. Users can download directly via IPFS (faster, decentralized) or via the .onion gateway (slower, but works without IPFS). IPFS gateway on .onion: run an IPFS HTTP gateway as part of the hidden service (IPFS daemon with API on localhost, Nginx proxies /ipfs/ requests to the gateway). Users accessing the .onion service can retrieve IPFS content via the gateway without needing their own IPFS node.