Run the local preview

What you need

• Docker Engine 20.10+ and Docker Compose v2
• bash 4+, curl, python3
• A few minutes for Docker to pull the preview images and start the local stack

Prefer the raw markdown? Open docs/LOCAL_QUICKSTART.md.

1. Copy the env template

cp local.env.example .env.local

The template is marked LOCAL ONLY and ships with deliberately small budgets (BUDGET_MAX_QUERIES=10) so the circuit breaker fires within a handful of queries.

2. Bring up the stack

docker compose -f docker-compose.local.yml up -d

Three containers: a synthetic postgres-demo, the Supersonic core, and the DAL. Postgres is not published to the host — every request goes through the DAL.

3. Initialize

bash scripts/init_local_preview.sh

Prints, among other lines:

[INIT] supersonic /health OK
[INIT] dal /health OK
[INIT] dal /ready OK (DAL → Supersonic upstream reachable)
[INIT] registered demo user
[INIT] created demo connection
[INIT] demo_api_key=sk-supersonic-...
[INIT] demo_connection=demo (<uuid>)
[INIT] demo_agent_id=demo-agent
[INIT] demo_session_id=demo-session
[INIT] OK

Idempotent: re-running on the same volume detects the existing demo identity, resets it in place, and re-issues a fresh API key. The script touches only the demo row.

4. Run the smoke test

SUPERSONIC_API_KEY=<printed-by-init> bash scripts/local_smoke.sh

Drives valid SELECTs with the same (agent_id, session_id) until the budget is exhausted. Output:

[SMOKE] query accepted
[SMOKE] budget incremented (queries.used=1)
[SMOKE] budget exhausted (status=429 attempts=10)
[SMOKE] enriched envelope present (code, reason, action, identity, queries, rows, retryable=false)
[SMOKE] session blocked
[SMOKE] OK

5. Watch a real agent session

SUPERSONIC_API_KEY=<printed-by-init> CONNECTION_ID=<printed-by-init> bash examples/demo-agent-session/demo.sh

Pretty-prints the enriched BUDGET_EXHAUSTED envelope and verifies that reconnecting with the same session_id stays blocked.

What you will see

When the breaker fires, the response body is:

{
  "ok": false,
  "error": {
    "code": "BUDGET_EXHAUSTED",
    "reason": "session_query_limit_exceeded",
    "action": "session_blocked",
    "agent_id": "demo-agent",
    "session_id": "demo-session",
    "queries": { "used": 10, "limit": 10,   "remaining": 0   },
    "rows":    { "used": 50, "limit": 1000, "remaining": 950 },
    "budget_window": { "seconds": 300, "remaining_seconds": 247 },
    "tables_touched":  ["users"],
    "columns_touched": ["id", "name"],
    "retryable": false,
    "operator_note": "The query was blocked because this agent/session reached its configured budget. Reconnecting with the same session_id will not reset the budget within the active budget window."
  },
  "request_id": "dal-..."
}

This is not a database failure. ValkDB blocked the agent session because it exhausted its configured budget. Reconnecting with the same session_id does not reset the budget within the active window.

What this preview does not require

• No production database
• No external connection string
• No hosted ValkDB
• No cloud trust
• No request access
• No invite

Trust model

• The connection string used by the preview never leaves the user's machine or local network
• The default database is synthetic — small users table generated by scripts/demo_seed.sql
• Traffic does not transit valkdb.dev or any subdomain
• Logs stay on the user's machine
• The local preview package lets the user inspect every input: compose, env, scripts, seed data, container logs, and HTTP responses
• The runtime core remains private at this stage

Full text: Trust Model.

After the local preview

There is no other onboarding path right now. The local preview is what we are validating. Hosted/SaaS distribution is not active.

Feedback

Blunt technical feedback only. Give technical feedback.