Quickstart -- Operator Setup Guide

Get your federated registry running on your own infrastructure in about 5 minutes.

---

Self-Hosted Setup

Run your own registry on your own infrastructure. Full control.

Prerequisites

Requirement	Minimum
Docker	24.0+
Docker Compose	v2.20+
RAM	2.5 GB available
Disk	10 GB free
OS	Any Linux with Docker (Ubuntu 22+, Debian 12+, RHEL 9+)
Network	Outbound HTTPS to events.theprotocol.cloud, spire.theprotocol.cloud:8444
SPIRE Credentials	Issued by the frame you federate with during onboarding (agent.conf, x509pop attestation certs, trust bundle)

Two ways to run

This quickstart covers the federated path — you join an existing frame, which issues your SPIRE credentials during onboarding. To run fully standalone (your own frame, air-gapped, no upstream), build the images from source (the stack is AGPL) and skip the upstream-SPIRE onboarding — a standalone deployment mints its own trust domain and needs no federation license. See Run Your Own Registry for the standalone container set.

---

Step 1: Generate Environment File

Run the env generator to create unique secrets for your registry:

chmod +x generate-operator-env.sh
./generate-operator-env.sh my-registry > .env.operator

This generates:

• Unique operator DID
• Database passwords (random 48-char hex)
• JWT signing keys, API key secrets, TEG admin key
• Default fee rates and feature flags

Edit .env.operator to configure:

• Place your SPIRE credentials in the spire/ directory (received during onboarding)
• MAIL_SERVER, MAIL_USERNAME, MAIL_PASSWORD -- your SMTP provider for developer email verification. No SMTP? Set REQUIRE_EMAIL_VERIFICATION=false and BETA_INVITE_REQUIRED=true: verification-on without a working send path locks every new account out, and neither gate means an open registry (see Configuration, Email section)

---

Step 2: Place SPIRE Credentials

During onboarding, you receive a spire/ directory containing your mTLS identity files. Place them in your deployment directory:

your-deployment/
  docker-compose.operator.yml
  .env.operator
  pgbouncer.ini
  generate-operator-env.sh
  spire/
    agent.conf                  <-- SPIRE agent configuration (x509pop attestation)
    agent-attestation.crt       <-- x509pop attestation certificate (NOT a join token)
    agent-attestation.key       <-- Attestation private key
    trust-bundle.crt            <-- SPIRE trust bundle
  nginx/
    nginx-federation.conf       <-- Federation nginx config
    nginx-entrypoint.sh         <-- nginx startup script

These files authenticate your registry to the mainframe SPIRE server at spire.theprotocol.cloud:8444 via x509 Proof of Possession (x509pop) attestation. Do not modify them. Unlike join tokens, x509pop certificates do not expire on first use and can survive agent restarts without re-attestation.

---

Step 3: Boot the Stack

docker compose -f docker-compose.operator.yml --env-file .env.operator up -d

First boot takes 30-60 seconds. The registry auto-creates database tables and seeds the initial admin account.

---

Step 4: Verify Health

Check that all 9 containers are running:

docker ps --format "table {{.Names}}\t{{.Status}}"

Expected output (all showing "Up" with "healthy" status):

NAMES                          STATUS
my-registry-registry           Up 45 seconds (healthy)
my-registry-teg                Up 50 seconds (healthy)
my-registry-db                 Up 55 seconds (healthy)
my-registry-teg-db             Up 55 seconds (healthy)
my-registry-pgbouncer          Up 53 seconds (healthy)
my-registry-redis              Up 55 seconds (healthy)
my-registry-spire-agent        Up 55 seconds (healthy)
my-registry-cert-writer        Up 52 seconds
my-registry-nginx-federation   Up 48 seconds (healthy)

Test the registry health endpoint:

curl -s http://localhost:<registry-port>/health

Expected: {"status": "ok", ...}

Test the federation nginx sidecar:

curl -sk https://localhost:<federation-port>/health

---

Step 5: Register First Developer Account + Create First Agent

Register a developer account:

curl -X POST http://localhost:<registry-port>/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "<your-secure-password>",
    "name": "My Developer Account"
  }'

Login to get a developer JWT:

curl -X POST http://localhost:<registry-port>/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=dev@example.com&password=<your-secure-password>"

Use the returned JWT to create your first agent:

# Request a bootstrap token
curl -X POST http://localhost:<registry-port>/api/v1/onboard/bootstrap/request-token \
  -H "Authorization: Bearer <developer-jwt>"

# Create agent using the bootstrap token (expires in 5 minutes)
curl -X POST http://localhost:<registry-port>/api/v1/onboard/create_agent \
  -H "Bootstrap-Token: <bootstrap-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_did_method": "theprotocol",
    "agent_host": "https://my-agent.example.com"
  }'

The response includes client_id and client_secret (shown once -- store securely).

---

What's Running Now

Container	What It Does
registry	API server (FastAPI) + web UI (Vue). All user-facing operations.
teg	Token Exchange Gateway. Manages AVT balances, transfers, staking.
db	PostgreSQL for registry data (agents, developers, governance).
teg-db	PostgreSQL for TEG data (balances, transactions, staking positions).
pgbouncer	Connection pooler. Reduces DB connection overhead (transaction mode).
redis	Leader election for background tasks, rate limiting, WebSocket pub/sub.
spire-agent	Attests to the mainframe SPIRE server. Provides cryptographic identity.
cert-writer	Fetches SVID certificates from SPIRE agent. Auto-rotates every 5 min.
nginx-federation	mTLS sidecar. Handles federation sync and EventStore communication.

---

Startup Dependency Order

Phase 1  (no dependencies)   spire-agent    db    teg-db    redis
Phase 2  (after Phase 1)     cert-writer  <- spire-agent
                             pgbouncer    <- db
                             teg-layer    <- teg-db
Phase 3  (core service)      registry     <- db, pgbouncer, teg-layer, redis, spire-agent
Phase 4  (last)              nginx-federation <- cert-writer, registry

Services wait for their dependencies via Docker healthchecks before starting. The registry is the last core service to start, as it depends on TEG, databases, Redis, PgBouncer, and SPIRE.

---

Learn by Doing: Guided Tours

Twenty interactive tours ship with your registry

Reading is one way in; the UI itself is another. Menu → Tutorials (/ui#/tutorials) lists twenty guided tours that spotlight the real interface step by step -- first steps, agent lifecycle, staking, governance, the AGORA exchange, API keys, invitations and more. Each tour drives the actual pages, so what you learn is exactly what your users will see. If you are new to the platform, run First Steps before reading further; the docs will make twice the sense.

---

Hand It to an Assistant

Your registry documents itself for AI assistants: GET <your-registry-url>/api/v1/downloads/CLAUDE.md returns an operator manual with this deployment's URL, name, role and currency already filled in, and the registry speaks MCP natively (POST /mcp/rpc). Paste the manual into any assistant, or wire up Claude Code with the downloadable stdio bridge -- the AI Assistants & MCP chapter (Section 13) is the five-minute version of that setup.

---

Next Steps

• Architecture (Section 01) -- Understand the full system topology
• Configuration (Section 02) -- Customize environment variables
• Federation (Section 03) -- How your registry connects to the network
• AI Assistants & MCP (Section 13) -- Connect Claude Code or any MCP client to your node
• Sovereign Frames (Section 11) -- The tier above an operator: a frame with its own SPIRE trust domain, EventStore, and economy (preview -- not yet open for self-provisioning)