Run Sparq locally

RequirementsCopy Anchor Link

Docker with Compose v2, uv, curl, openssl and Python 3.

Start the stackCopy Anchor Link

scripts/sparq.sh up

The script:

1. creates a local .env with random passwords and a signing key for delegated tool tokens;
2. starts PostgreSQL 16 with pgvector, and Redis 7;
3. creates the database roles and runs the migrations;
4. creates the first operator key once and writes it to .secrets/operator-api-key (file mode 600, never printed);
5. starts the API behind a local edge on http://127.0.0.1:8000 and checks /health/ready and /v1/whoami.

Other commands: scripts/sparq.sh status, logs, restart and down. Stopping never deletes data.

Call the local APICopy Anchor Link

curl -H "Authorization: Bearer $(cat .secrets/operator-api-key)" http://127.0.0.1:8000/v1/whoami

An operator key answers with principal_type service. Then follow the quickstart with SPARQ_API_URL=http://127.0.0.1:8000.

Load a model registryCopy Anchor Link

The model registry lists the deployments the Frontier Gateway may use. It names each provider key by reference (env:NAME), never by value.

uv run python -m sparq_control.admin registry load config/registry/dev.json

The file is validated as a whole and applied in one audited transaction; loading the same file again changes nothing. Read it back with the models operations: model classes, deployments, routing rules and prices.