Store IPFS content on Filecoin's decentralized storage network with verifiable persistence.
Register for updates and a later 2025 Q4 GA announcement at filecoin.cloud.
Filecoin Pin is a fully decentralized persistence layer for IPFS content using the global network of Filecoin storage providers with cryptographic guarantees.
When you use Filecoin Pin, your IPFS data gains:
- Verifiable persistence - Storage providers must cryptographically prove daily that they continue to store and serve your data
- Economic incentives - You only pay when storage proofs are successfully delivered and verified onchain
- Decentralized infrastructure - Your data can be stored across a global network of independent storage providers
- Seamless IPFS integration - Continue using standard IPFS Mainnet tooling (e.g., Kubo, Helia, HTTP Gateways) while gaining Filecoin's persistence guarantees
- Sovereign data - Choose your providers, audit storage proofs and payments onchain, with no dependency on a single company
Filecoin Pin is designed for developers building on IPFS who need trustless, economically-incentivized persistence for their content. Whether you're building dApps, CI/CD workflows, static websites, AI agents, or other applications, Filecoin Pin provides the missing persistence layer for IPFS.
Filecoin Pin offers multiple affordances to integrate Filecoin storage into your workflow:
Upload IPFS files directly to Filecoin via the command line. Perfect for developers who want to integrate Filecoin storage into scripts, workflows, or local development environments.
- Repository: This repo (filecoin-project/filecoin-pin)
- Documentation:
- Run
filecoin-pin --helpto see all available commands and options. - CLI Walkthrough
- Run
- Installation:
npm install -g filecoin-pin
Automatically publish websites or build artifacts to IPFS and Filecoin as part of your CI/CD pipeline. Ideal for static websites, documentation sites, and automated deployment workflows.
- Repository: This repo (see upload-action/)
- Documentation:
- Example in Production: filecoin-pin-website CI pipeline
Opinionated JavaScript library with utilities for common functionality across different use cases. Use these modules directly in your Node.js or browser applications.
- Repository: This repo (see
src/core/and package exports). - Installation:
npm install filecoin-pin - Exports: Core modules for CAR files, payments, Synapse SDK integration, uploads, and UnixFS operations
Run a localhost IPFS Pinning Service API server that implements the IPFS Pinning Service API specification. This allows you to use standard IPFS tooling (like ipfs pin remote) while storing data on Filecoin.
- Repository: This repo (
filecoin-pin servercommand in CLI) - Usage:
PRIVATE_KEY=0x... npx filecoin-pin server - Status: Works and is tested, but hasn't received as many features as the CLI. If it would benefit your usecase, please comment on tracking issue so we can be better informed when it comes to prioritizing.
Web-based management console for monitoring and managing your Filecoin Pin deployments. This is effectively a Web UI equivalent to the CLI.
- Status: Planned
- Tracking: See issue #74 for updates. Please leave a comment about your usecase if this would be particularly beneficial.
See Filecoin Pin in action:
- upload-action - Example GitHub Action workflows demonstrating automated IPFS/Filecoin uploads
- filecoin-pin-website - Demo dApp showing browser-based file uploads to Filecoin (Walkthrough)
Filecoin Pin bridges IPFS and Filecoin to provide verifiable persistence for content-addressed data:
This repository contains multiple affordances for user interaction and a shared library for consistent functionality:
The Synapse SDK is the main library, as it's doing the work of interfacing with the rest of Filecoin Onchain Cloud including smart contracts, Filecoin Storage Providers, and more.
Helia is leveraged for turning files and directories into IPFS compatible data, which we output in CAR format.
The affordances were discussed more above. All affordances use the same core library, ensuring consistent behavior and making it easy to add new interfaces in the future.
- Node.js 24+ for CLI and library usage
- Filecoin Calibration testnet wallet with:
- Test FIL for transaction gas (Faucet)
- Test USDFC stablecoin for storage payments (USDFC Faucet)
npm install -g filecoin-pin# 0. Set your PRIVATE_KEY environment variable or pass it via --private-key to each command.
# 1. Configure payment permissions (one-time setup)
filecoin-pin payments setup --auto
# 2. Upload a file to Filecoin
filecoin-pin add myfile.txt
# 3. Verify storage with cryptographic proofs
filecoin-pin data-set <dataset-id>For detailed guides, see:
- CLI: Complete CLI walkthrough
- GitHub Action: CI/CD integration guide
Configuration of the Filecoin Pin CLI can be performed either with arguments, or environment variables.
The Pinning Server requires the use of environment variables, as detailed below.
-h,--help: Display help information for each command-v,--version: Output the version number--private-key: Ethereum-style (0x) private key, funded with USDFC (required)--rpc-url: Filecoin RPC endpoint (default: Calibration testnet)
Other arguments are possible for individual commands, use --help to find out more.
# Required
PRIVATE_KEY=0x... # Ethereum private key with USDFC tokens
# Optional
RPC_URL=wss://... # Filecoin RPC endpoint (default: Calibration testnet)
# Optional for Pinning Server Daemon
PORT=3456 # Daemon server port
HOST=localhost # Daemon server host
DATABASE_PATH=./pins.db # SQLite database location
CAR_STORAGE_PATH=./cars # CAR file storage directory
LOG_LEVEL=info # Logging verbosity (info, debug, error)When DATABASE_PATH and CAR_STORAGE_PATH are not specified, data is stored in platform-specific locations:
- Linux:
~/.local/share/filecoin-pin/ - macOS:
~/Library/Application Support/filecoin-pin/ - Windows:
%APPDATA%/filecoin-pin/
Want to contribute to Filecoin Pin or run it locally?
# Clone and install
git clone https://github.com/filecoin-project/filecoin-pin
cd filecoin-pin
npm install
# Run the Pinning Server
npm run dev
# Run tests
npm test
# Compile TypeScript source
npm run build
# Run the cli
# This is the equivalent of running `filecoin-pin` if you had it installed globally (e.g., `npm install filecoin-pin -g`).
# It's like doing `npx filecoin-pin` that isn't stuck on that version until you `run npm install filecoin-pin -g` again.
node ./dist/cli.jsnpm run test # All tests
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run lint:fix # Fix formatting- Issues: Found a bug or have a feature request? Open an issue in this repository
- Community Discussion: Join the conversation in Filecoin Slack's public #fil-foc channel
- documentation/ - (Coming Soon) Additional documentation about how filecoin-pin works, design decisions, etc.
- docs.filecoin.io - Filecoin Pin guides and tutorials
Dual-licensed under MIT + Apache 2.0
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
