Skip to content

serve

Start the Piri server and begin participating in the Storacha network.

This is a long-running process that operates your storage node. Once started, Piri will:

  1. Accept storage requests - Receive and store data from clients via the UCAN protocol
  2. Generate PDP proofs - Create Provable Data Possession proofs on a regular schedule to demonstrate you're storing data correctly
  3. Respond to challenges - Submit proofs to the on-chain PDP smart contract during challenge windows
  4. Publish to IPNI - Announce stored content to the InterPlanetary Network Indexer for discoverability
  5. Handle retrievals - Serve stored data back to clients on request

The server runs continuously, writing logs to the terminal. For production deployments, you should run it as a systemd service or use a process manager to ensure it restarts on failure.

Prerequisites

Before running this command:

  1. Run piri init to generate a configuration file - this registers your node with the network and creates your proof set
  2. Ensure your TLS reverse proxy is running (Nginx with SSL certificates)
  3. Verify your Lotus node is synced and accessible

Configuration

The server reads its configuration from a TOML file generated by piri init. You can specify the config file path with --config, or place it in the default location (~/.config/piri/config.toml) for automatic loading.

Most flags below are already set in your config file - you typically only need --config to start the server. See the Configuration docs for details on all available settings.

Usage

piri serve [flags]

Flags

Flag Description Default
--config <path> Path to configuration file ~/.config/piri/config.toml
--host <host> Host to listen on localhost
--port <port> Port to listen on 3000
--public-url <url> URL the node is publicly accessible at
--network <network> Network the node operates on
--proof-set <id> Proof set ID to use with PDP
--lotus-url <url> WebSocket URL for Lotus node
--owner-address <address> Ethereum address to submit PDP proofs with (must be in piri wallet)

Example

piri serve --config=config.toml

▗▄▄▖ ▄  ▄▄▄ ▄   ▗
▐▌ ▐▌▄ █    ▄   █▌
▐▛▀▘ █ █    █  ▗█▘
▐▌   █      █  ▀▘

v0.2.1
did:key:z6MkhaXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Piri Running on: localhost:3000
Piri Public Endpoint: https://piri.example.com

Stopping the Server

Use Ctrl+C to gracefully stop the server. On shutdown, Piri will:

  • Wait for any active retrievals to finish
  • Wait for any in-progress chain tasks (proving, message sends) to complete
  • Force stop after 1 minute if tasks haven't completed

Before stopping for maintenance or upgrades, check if it's safe using piri status to ensure you're not in the middle of a challenge window.

See the Setup Guide for complete setup instructions and the Upgrading guide for safe update procedures.