IPFS + Filecoin for AI Model Weight Storage [2026]

Shipping multi-gigabyte AI weights through centralized object storage gives you one durable copy and one failure domain. A better pattern is to content-address the artifact with IPFS, then push the same payload into a Filecoin-backed service for long-term, provable storage. As of May 07, 2026, the practical CLI path is Kubo for local IPFS operations and Storacha, which is where the current Web3.Storage documentation now points.

Prerequisites

Step 1: Prepare the weight bundle

Do not upload a loose collection of files with no manifest. For model distribution, you want a deterministic folder, explicit checksums, and metadata that tells downstream users exactly what they fetched.

1. Create a clean release directory for the model files.

mkdir -p weights/my-llm-7b
cp model.safetensors config.json tokenizer.json weights/my-llm-7b/

2. Generate checksums from inside that directory so later verification is trivial.

cd weights/my-llm-7b
sha256sum model.safetensors config.json tokenizer.json > SHA256SUMS
cd ../..

3. Add a minimal manifest. This is the human-readable contract for the bundle.

cat > weights/my-llm-7b/manifest.json <<'EOF'
{
  "model": "my-llm-7b",
  "format": "safetensors",
  "created_at": "2026-05-07T00:00:00Z",
  "files": [
    "model.safetensors",
    "config.json",
    "tokenizer.json",
    "SHA256SUMS"
  ]
}
EOF

This structure gives you three things you will need in production:

• A stable directory boundary for a single root CID.
• A checksum file that survives transport across gateways and peers.
• A manifest your deployment system can inspect before loading the weights.

Step 2: Publish to IPFS and Filecoin

Now you will do two separate but complementary operations: add the bundle to your local IPFS node, then upload it to a Filecoin-backed service that keeps it available over IPFS.

1. Initialize and start your local Kubo node.

ipfs init --profile server
ipfs daemon

The --profile server flag is the right default on a VPS or public host because it disables local-network discovery behavior that does not belong in a data-center environment.

2. In a second terminal, add the weight directory to IPFS.

ipfs add -r weights/my-llm-7b

Keep the final line from the output. That last CID is the root directory CID for the whole model bundle. Also note that content added with ipfs add is pinned locally by default, which protects it from garbage collection on your node.

3. Install the current Filecoin-backed upload CLI and create a space.

npm install -g @storacha/cli
storacha login you@example.com
storacha space create model-weights-prod

4. Upload the same directory and capture the verbose output.

storacha up weights/my-llm-7b --verbose

On current docs, this upload path content-addresses your files, packs them into one or more CAR shards, and sends them for indexing and inclusion in Filecoin storage deals. For larger weight bundles, expect multiple shard CIDs and multiple Piece CID lines. Copy two values from the upload log:

• The root content CID or gateway URL for the uploaded model bundle.
• At least one printed Piece CID for Filecoin verification.

Step 3: Verify retrieval and deals

Verification is the difference between a demo and an engineering workflow. You want to prove both of these statements:

• The artifact can be retrieved by CID over IPFS.
• The uploaded data has corresponding Filecoin deal information.

Verify retrieval from your local IPFS node

export ROOT_CID=bafy...your_root_cid...
ipfs get /ipfs/$ROOT_CID -o restored-model
cd restored-model/my-llm-7b
sha256sum -c SHA256SUMS

If the bundle is intact, every file should return OK. That is the quickest way to prove the fetched weights match the release you originally prepared.

Verify Filecoin deal information

export PIECE_CID=bafk...your_piece_cid...
storacha can filecoin info $PIECE_CID

This command should eventually print deal metadata for that piece, including aggregate CID, storage provider IDs, and deal IDs. That is your operational proof that the data has moved beyond a local IPFS pin and into Filecoin-backed storage.

Expected output

• ipfs daemon ends with Daemon is ready.
• ipfs add -r prints per-file CIDs and a final directory CID.
• storacha up --verbose prints a gateway URL and one or more Piece CID lines.
• sha256sum -c SHA256SUMS reports OK for every file.
• storacha can filecoin info prints at least one Provider and Deal ID once the piece is indexed into deals.

Troubleshooting Top 3

1. Upload succeeded, but storacha can filecoin info shows no deals yet

• This usually means the upload is accepted but deal indexing is not complete yet.
• Storacha aggregates uploaded data before it lands with Filecoin storage providers, so verification can lag behind the initial upload.
• Wait, then rerun the same filecoin info command against the same Piece CID.

2. The gateway URL works, but ipfs get is slow or hangs locally

• Make sure your local ipfs daemon is still running in the first terminal.
• If this is a cloud host, initialize with ipfs init --profile server rather than the desktop default.
• Remember that local retrieval depends on your node being online and connected to peers that can serve the CID.

3. Checksum verification fails after restore

• The bundle changed after you generated SHA256SUMS.
• You uploaded a different directory than the one you hashed.
• A single-byte change produces a different CID, so rebuild the release directory, regenerate checksums, and publish a new immutable version.

What’s next

Once the manual flow works, move it into automation and treat the model bundle like any other release artifact.

• Automate uploads in CI using storacha key create, storacha delegation create, storacha space add, and storacha up.
• Publish a small index file that maps semantic model versions to root CIDs so clients can resolve v1.2.0 to a specific immutable artifact.
• Use --json in automation when you want machine-readable CID capture for deployment metadata.
• Switch to --car when your pipeline already emits CAR files and you want a portable archive boundary across tools.

The core pattern is simple: build a deterministic model directory, hash it into a CID with IPFS, and verify that a Filecoin-backed service has taken custody of the data. Once that is in place, model distribution stops depending on one region, one bucket, or one vendor account.