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

Run it

curl -O https://valkdb.dev/downloads/valkdb-local-preview.tar.gz
tar -xzf valkdb-local-preview.tar.gz
cd valkdb-local-preview-*

cp local.env.example .env.local
docker compose -f docker-compose.local.yml up -d
bash scripts/init_local_preview.sh
SUPERSONIC_API_KEY=<printed-by-init> bash scripts/local_smoke.sh
SUPERSONIC_API_KEY=<printed-by-init> CONNECTION_ID=<printed-by-init> bash examples/demo-agent-session/demo.sh

Verify the download:

curl -O https://valkdb.dev/downloads/SHA256SUMS
sha256sum -c SHA256SUMS

What you will see

The smoke output when the breaker fires:

[SMOKE] query accepted
[SMOKE] budget incremented
[SMOKE] budget exhausted (status=429 attempts=10)
[SMOKE] enriched envelope present
[SMOKE] session blocked
[SMOKE] OK

The response body of the blocked query:

{
  "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 },
    "tables_touched":  ["users"],
    "columns_touched": ["id", "name"],
    "retryable": false
  }
}

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 the package contains

• docker-compose.local.yml — local stack (postgres-demo, supersonic, dal)
• local.env.example — env template, all values are LOCAL ONLY placeholders
• scripts/init_local_preview.sh — provisions the demo identity (idempotent)
• scripts/local_smoke.sh — drives the budget to exhaustion
• scripts/local-postgres-init/ + scripts/demo_seed.sql — synthetic Postgres seed
• examples/demo-agent-session/demo.sh — pretty-printed agent demo
• docs/LOCAL_QUICKSTART.md — full step-by-step
• docs/TRUST_MODEL.md — what stays on your machine
• README.md — local-preview README
• VERSION

What the package does NOT contain

• No production docker-compose.yml
• No production Dockerfiles
• No Railway configs or deploy scripts
• No internal reports or pentest tooling
• No runtime source (the core remains private at this stage)
• No secrets, no real .env, no credentials

How the runtime is provided

The package uses prebuilt Docker images for the ValkDB runtime. The first docker compose up -d pulls them from the public registry pinned in local.env.example (default: ghcr.io/axellopezuy-cmd/valkdb-supersonic-preview and ghcr.io/axellopezuy-cmd/valkdb-dal-preview). The runtime source is not included in this preview package. No open source is implied.

If you operate in an air-gapped environment, override the image references via VALKDB_SUPERSONIC_IMAGE and VALKDB_DAL_IMAGE in .env.local after re-tagging the images on your private registry.

What stays on your machine

• The connection string never leaves the local Docker network.
• The default database is synthetic.
• Traffic does not transit valkdb.dev or any subdomain at runtime.
• Logs stay on your machine.
• Nothing is sent back to us automatically. Nothing.

Full text: Trust Model.

Feedback

Blunt technical feedback only. The whole point of the local preview is for you to look at it before deciding whether the chain identity → session budget → circuit breaker matches a real problem in your stack.