Getting started

Core concepts

A short glossary of the moving parts. Once these click, the rest of the docs read quickly.

Hosts and borrowers

A host (or provider) runs a model on hardware they own and makes it available to the network. A borrower sends inference requests with an API key and pays in credits. The same account can be both — host while you sleep, borrow while you build.

Sessions and provider models

When a host comes online it opens a session and heartbeats to stay live (a session is considered live within a ~90s window of its last heartbeat). Each session advertises one or more provider models, each with a warmth status:

  • ready / warm — loaded in GPU memory, responds instantly.
  • loadable — advertised but not yet loaded; the first request triggers a warm-up (seconds to a couple of minutes).

Dispatch

The dispatch layer is the matchmaker. When a request arrives it finds a live host serving the requested model and hands off the job over Supabase Realtime. If none is free, dispatch can wait for capacity (up to ~60s) rather than reject. Two headers steer it:

FieldDescription
X-Pied-Piper-HostTarget a specific host instead of the normal queue. Required to use priority.
X-Pied-Piper-PriorityJump that host's priority lane. Bills price × priority multiplier. Requires X-Pied-Piper-Host.

Without these headers a request joins the normal queue and bills the standard price of whichever host picks it up. See Marketplace & priority.

Credits

Credits are the unit of account. Borrowers spend them per request; hosts earn them per request served. Credits are priced against USD with a live rate shown in the header (the $1 ≈ N credits pill), and can be bought or withdrawn through the wallet. Full mechanics live in Credits & wallet and Pricing.

One mental model
landing → platform(the API + marketplace you're reading about) → SDK (how you call it) → hosting clients (browser, extension, native node). Everything in these docs sits inside that chain.

The stack underneath

  • Next.js App Router for the web app and the /v1 API.
  • Supabase — Postgres with row-level security, plus Realtime for the dispatch handoff.
  • Privy for auth (email or wallet).
  • viem on Sepolia for the on-chain side of credits.
  • WebGPU / web-llm for in-browser hosting; llama.cpp for native nodes.