smelt

Smelt ⚗️

The Smelter: A complete Forge 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 Forge 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 engine 25+ (verified by the Makefile; older engines silently degrade on healthchecks and break snapshot portability)
• Docker Compose
• Go 1.22+ (required for smelt generate, the multi-piri manifest generator, and for UCAN delegation proof generation)
• Linux or macOS host

Start the Network

git clone https://github.com/fil-forge/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)
# Visit http://localhost:15081 and click the link (or programmatically get
# messages from http://localhost:15081/api/messages and POST to the link).
guppy login your@email.com

# Create a storage space (returns the space DID on stdout)
export SPACE=$(guppy space generate)

# Add a source then upload the space
echo "Hello Forge" > /tmp/hello.txt
guppy upload source add "$SPACE" /tmp/hello.txt
guppy upload "$SPACE"

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

What's Running

All host ports live in a dedicated 15XXX range to avoid collision with common dev tools (3000, 5432, 6379, 8000, 8080, 8545, 9000, ...).

Architecture

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

    subgraph Services
        upload["upload :15060"]
        piri["piri :15100"]
        indexer["indexer :15050"]
        signing["signing-service :15030"]
        delegator["delegator :15040"]
    end

    subgraph Infrastructure
        blockchain["blockchain :15000"]
        ipni["ipni :15090"]
        redis["redis :15020"]
        dynamodb["dynamodb-local :15010"]
        minio["minio :15070"]
        email["smtp4dev :15080"]
    end

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

    upload --> piri
    upload --> indexer
    upload --> minio
    upload --> dynamodb
    upload --> email

    piri --> signing
    piri --> ipni
    piri --> delegator
    piri --> indexer
    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.

Snapshots

Cold-boot takes ~45s (contract deploy + piri registration); restoring a saved snapshot reaches the same state in ~10s. Capture a healthy stack with ./smelt snapshot save NAME, then later make up SNAPSHOT=NAME to resume.

Snapshots are portable across Linux/macOS checkouts: commit them under snapshots/ at the project root to share with teammates, or keep personal ones in the gitignored generated/snapshots/. Save captures each service's image reference and content digest, so load warns both when your .env points at a different tag and when a rolling tag was re-pulled between save and load.

The full picture — what's captured, session semantics, workflows, gotchas — lives in docs/SNAPSHOTS.md.

Where to Go Next

• Getting Started — First-time setup, key generation, and upload walkthrough
• Multi-Piri Configuration — Running multiple piri nodes via smelt.yml
• Snapshots — Capture and restore stack state to skip cold-boot time
• Architecture Guide — How the services connect and why
• Developing Across Service Repos — Run local changes to piri/sprue/libforge/etc. in the stack via go.work
• 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.