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.example.com, spire.example.com: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

---

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.example.com: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 '{
    "name": "My First Agent",
    "description": "A test agent on my registry",
    "capabilities": ["echo", "chat"]
  }'

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.

---

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
• 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)