Skip to main content
This guide walks you through a full local development environment: the Python backend, the FastAPI proof API, the Next.js frontend, the test suite, and the optional Docker agent container.

​
Backend

​
Requirements

  • Python 3.11+ — check with python --version
  • git

​
Install

Create a virtual environment from the repository root (veridex-arena/) and install all extras:
The extras bundle the components you need for local development:
If you prefer uv, the repository ships a uv.lock. Run uv sync --extra api (or uv sync --all-extras for the full set) and prefix subsequent commands with uv run instead of activating the venv.

​
Start the API server

The API binds to http://localhost:8000 by default. --reload enables hot-reloading during development. Key endpoints include:
  • POST /demo/run — runs agents, seals, scores, and anchors a demo competition
  • GET /leaderboard — returns CLV-ranked results
  • POST /runs/{run_id}/verify — recomputes the proof from sealed evidence
To change the bind address or port, set HOST and PORT in veridex/.env (see Configuration).

​
Database (optional for local dev)

By default, with no DATABASE_URL set, Veridex uses an in-memory store — state is lost on restart, but the full proof pipeline works without a database. To persist agent instances and run history across restarts, set DATABASE_URL in veridex/.env to a reachable Postgres connection string:
If DATABASE_URL is set but the database is unreachable, Veridex fails closed at startup — it never silently falls back to the in-memory store. Only leave DATABASE_URL unset (not set-to-wrong) to use in-memory mode.

​
Frontend

​
Requirements

  • Node.js (LTS recommended)
  • pnpm

​
Install and start

Open http://localhost:3000 in your browser. The web app expects the API to be running at the URL specified by NEXT_PUBLIC_API_BASE in apps/web/.env.local. For local development this is typically http://localhost:8000. The frontend provides the full product surface: Agent Studio, Live Cockpit, Decision Inspector, Proof Card, Leaderboard, Operator Dashboard, and Head-to-Head Duel.

​
Test Suite

This runs 1,000+ backend tests, all fully offline and deterministic. The suite includes:
  • A byte-for-byte golden seal suite that guards the sealed path — every refactor since the baseline has left the sealed bytes provably identical.
  • A trust-path import audit asserting zero LLM SDK imports in the law, checks, scoring, verifier, and policy code paths.
  • Adversarial tamper tests — for example, doctoring a persisted clv_bps row correctly triggers a metrics_recomputed failure.
No credentials, database, wallet, or network access are needed to run the full suite.

​
Docker (Agent Container)

To build and run the standalone agent container:
The container uses the same single runner seam as the deploy endpoint. Pass credentials at runtime via --env-file — never bake secrets into the image.

​
What Works Offline vs. What Requires Credentials

See the Configuration page for the full list of environment variables and how to set them.