Set up a local Stratl

Stratl is three repositories side by side in one folder. Each has its own git history and deploys on its own.

Folder	What	Stack	Deploys to
stratl-backend/	The API, both SDKs, the Go verifier, the record specification, deploy files	Python 3.12, FastAPI, PostgreSQL; Go; TypeScript	Railway, with AWS for custody
stratl-web/	The portal	Vite, React 19, Tailwind v4	Vercel
stratl-website/	The public site at stratl.ai	Astro, static	Vercel
stratl-docs/	This site	Astro Starlight	Vercel

Tools you need

1. Homebrew (macOS) or your package manager, then:

   brew install uv pnpm go postgresql@16 gh

   uv runs Python and manages virtual environments; pnpm runs JavaScript projects; Go builds the verifier; PostgreSQL is the index database. Node 22 comes with pnpm’s use-node-version or install it separately.

2. Clone the repositories next to each other:

   mkdir stratl && cd stratl
   gh repo clone Metricall-AI-Lab/stratl-platform-backend stratl-backend
   gh repo clone Metricall-AI-Lab/stratl-platform-web stratl-web
   gh repo clone Metricall-AI-Lab/stratl-website
   gh repo clone Metricall-AI-Lab/stratl-docs

3. Install everything in the backend:

   cd stratl-backend
   make setup        # uv sync, pnpm install, go mod download
   make up           # starts local PostgreSQL and creates the stratl role and databases
   make migrate      # applies the schema

   make up also copies api/.env.example to api/.env if it does not exist. Every value in it works on a laptop; nothing is required beyond the first block.

4. Run the API:

   make api          # http://localhost:8000, reloads on change

   The first start creates a development signing key under api/.stratl-custody/ and logs that custody is local. Timestamps come from the real authorities.

5. Run the portal in a second terminal:

   cd ../stratl-web && pnpm install && pnpm dev     # http://localhost:5173

   The portal calls /api, which the dev server forwards to localhost:8000, so the session cookie stays first-party. Sign in with any email: with no email provider configured, the code is printed in the API log and shown on the sign-in screen.

6. Optional. The website: cd ../stratl-website && pnpm install && pnpm dev (port 4321). These docs: cd ../stratl-docs && pnpm install && pnpm dev (port 4322). The verifier: make cli in the backend builds cli/bin/stratl.

Two things to know before you sign in locally

Signing up locally creates the first workspace as the default tenant. Test sign-ups with other emails create more workspaces; clean the auth tables between experiments (make fresh wipes the database and the custody folder). And if you put a real email provider key into api/.env, codes and invitations really send.

Seed data

make seed writes sixty realistic decisions, including adverse ones, into the local workspace so the portal has something to show. make example runs the refund-agent example against the local API, which is the best way to see the Python SDK in use: it reads tickets, decides refunds (with Claude if ANTHROPIC_API_KEY is set, otherwise with built-in rules), asks a human to approve large ones, issues them and records every step.

The checks

Every change must pass these before it ships. CI runs the same commands.

make lint          # ruff (Python), tsc and eslint (TypeScript), go vet
make test          # pytest for the API and the Python SDK, vitest for the TypeScript SDK, go test
make conformance   # Python, TypeScript and Go hash every golden fixture identically

In the portal: pnpm lint && pnpm typecheck && pnpm test && pnpm build. In the website and these docs: pnpm build, which runs the Astro checks first. CI also scans for leaked secrets and vulnerable dependencies. Security in engineering.

Tests and the database

The API tests use a second database, stratl_test, created by make up. They truncate every table at the start of each test, run with authentication off and the scheduler disabled, and never touch stratl_dev. Custody in tests is the local backend; the S3 and KMS backend is tested with an in-process AWS simulator, and the customer-cloud backends with stand-ins. Anything those cannot prove is proved by the check scripts against real accounts. Proving connectors and custody.

Where things are

stratl-backend/
  api/app/        the FastAPI service: auth, ingest, custody, index, retention, evidence, notices, packs
  api/connectors/ pull connectors: langfuse, anthropic_compliance, otel
  api/packs/      framework packs (YAML)
  api/scripts/    seed, check_custody, prove_connector
  sdk/python/     the stratl package; owns the Python record format implementation
  sdk/typescript/ @stratl/sdk
  cli/            the Go verifier; also compiled to WebAssembly for the portal
  spec/           SRF schema, spec, fixtures, conformance
  deploy/         CloudFormation, the Google Cloud and Azure set-up scripts, docker-compose
  planning/       the product plan and the deployment guide

The one rule that matters most when you change code: there is exactly one implementation of the record format per language, and the API imports the Python one. Nothing re-implements hashing.