smelt

Smelt ⚗️

The Smelter: A complete Storacha network running on your laptop. Upload your first file in under five minutes.

Smelt is a Docker Compose environment that runs every service in the Storacha distributed storage network locally. It exists so you can test changes, debug integrations, and develop features without deploying anything to production—or waiting for anyone else.

Quick Start

Prerequisites

• Docker and Docker Compose
• Go 1.22+ (for key and proof generation)

Start the Network

git clone https://github.com/storacha/smelt.git
cd smelt
make up

The first run takes a minute or two while Docker pulls images and generates cryptographic keys. Subsequent starts are faster.

Verify Everything is Running

make status

Wait until all services show healthy. This typically takes 30-60 seconds after make up completes.

Your First Upload

# Enter the guppy client container
make shell-guppy

# Create an account (inside the container)
guppy login your@email.com

# Create a storage space
guppy space create my-space

# Upload something
echo "Hello Storacha" > /tmp/hello.txt
guppy upload /tmp/hello.txt

You now have content stored on your local Storacha network, complete with blockchain proofs and content indexing.

What's Running

Architecture

flowchart TB
    subgraph Client
        guppy["guppy (CLI)"]
    end

    subgraph Services
        upload["upload :8080"]
        piri["piri :3333"]
        indexer["indexer :9000"]
    end

    subgraph Infrastructure
        blockchain["blockchain :8545"]
        signing["signing-service :7446"]
        delegator["delegator :8081"]
        ipni["ipni :3000"]
        redis["redis :6379"]
        dynamodb["dynamodb-local :8000"]
    end

    guppy --> upload
    guppy --> piri
    guppy --> indexer

    upload --> piri
    upload --> indexer

    piri --> signing
    piri --> ipni
    signing --> blockchain

    delegator --> dynamodb
    indexer --> redis
    indexer --> ipni

Data flow: Guppy sends upload requests to the upload service, which coordinates with piri (the storage node). Piri stores the content, submits PDP proofs to the blockchain via the signing service, and announces the content to IPNI for discovery. The indexer caches content claims for fast lookups.

Common Commands

Run make help for the complete list.

Where to Go Next

• Architecture Guide — How the services connect and why
• Troubleshooting — When things go wrong (they will)
• Extending Smelt — Adding services or modifying the environment

A Note on Naming

Smelt: to extract metal from ore by heating. Also a small fish, but that's less relevant here. The name suggests refining raw materials into something useful—an apt metaphor for a development environment that lets you extract working features from experimental code without the overhead of production infrastructure.