Quickstart

This walks you from nothing to a single OpenInfra node running a real workload and settling payment for it, on one machine. It uses the reference single-node deployment (deploy/kuma) as the node and the reference tenant (examples/coledex) as the workload.

Target time: ~15 minutes on a host that already has Docker.

Prerequisites

• Linux host with Docker + Compose v2
• Go 1.22+ (only if you want to build openinfra-cli for admin bootstrap)
• Outbound internet (Solana devnet billing + image pulls)

1. Bring up the node

cp deploy/kuma/.env.example deploy/kuma/.env
# Edit deploy/kuma/.env: set a real JWT_SECRET — `openssl rand -hex 32`.
# Tune OPENINFRA_MAX_* to what this host can spare.

cd deploy/kuma
docker compose --env-file .env up -d

Four containers come up: control-plane Postgres, the api-server (HTTP :8082, gRPC :9092), a co-located provider agent, and a private image registry (:5000). See deploy/kuma/README.md.

2. Verify it’s healthy

curl -fsS http://localhost:8082/healthz && echo OK
docker compose --env-file .env ps        # all four Up

3. Bootstrap an admin

The first user must be promoted out-of-band (deliberately not an API endpoint — see ARCHITECTURE.md, Block I):

# Register a user via the API, then promote it with the CLI:
go run ./cmd/cli promote you@example.com   # uses DATABASE_URL

DATABASE_URL for this stack is postgres://openinfra:openinfra@localhost:5433/openinfra?sslmode=disable.

4. Register an example service

The reference tenant ships ready-to-run manifests under examples/coledex/manifests/. The operational register scripts upsert them into the control plane via POST /api/v1/admin/catalog/services?upsert=true:

# Each script reads a manifest from examples/coledex/ and upserts it.
deploy/local-pilot/register-coledex-pg-backup-ssh.sh

Read one manifest to see the shape of a service — kind, resources, optional schedule_cron, and a secret_validation block interpreted by the generic internal/secretrules validator (no tenant-specific code in core; see examples/coledex/README.md).

5. Run a workload and watch it settle

POST /api/v1/workloads targeting the registered service schedules it onto this node. The agent runs the container, meters CPU + memory at millisecond precision, records completion, and the settlement path debits the tenant / credits the provider — on the internal ledger and onchain (Solana devnet by default).

The full lifecycle (admin login → tenant + credits → register → fire → poll for completion → verify the SPL transfer) is automated end-to-end in deploy/local-pilot/run-pilot.sh, which is the most accurate reference for exact request bodies. Point it at this stack via OPENINFRA_API=http://localhost:8082.

Where to go next

You want to…	Read
Understand the architecture	ARCHITECTURE.md
Package your own workload	examples/coledex/README.md
Onboard a second provider host	docs/HOME-LAB-ONBOARDING.md
Move off the LAN to a paid host	docs/HETZNER-MIGRATION.md
Run the metered/observability stack	docs/LOCAL-PILOT.md