Get started

Step 1: Start the database and migrate it

cd api
cp .env.example .env
uv sync
make db-up          # vector-enabled database image as container trovensa-db on localhost:5434, waits until healthy
make migrate        # alembic upgrade head with the owner DSN: 0001 to 0005 create 60 tables and seed the 10 personas
make dsn-check      # the application role cannot update, delete or truncate audit or signature rows

make db-up prints db healthy; the compose init script creates the application role trovensa_app and the owner role, and 0002 grants them (role split). The API and the worker use the application DSN; make migrate uses the owner DSN (MIGRATE_DATABASE_URL). Port 5434 is used because 5433 is taken on the development machine.

Step 2: Run the API and seed the illustrative program

make dev            # uvicorn app.main:app --reload on :8100

In a second shell:

cd api
curl -s localhost:8100/api/v1/health/ready     # {"status":"ok","version":"0.1.0","env":"dev","database":"ok"}
uv run python scripts/seed_illustrative.py     # organisation trovensa-demo, programs default and trv-101

The seed is idempotent. It creates organisation trovensa-demo with the program default and the program trv-101 (“Illustrative program TRV-101”), plus records whose titles start with “Illustrative:” and whose illustrative flag is true.

Step 3: Mint a development token

TOKEN=$(uv run python scripts/dev_token.py --user owner@example.com --org trovensa-demo --roles org_owner,program_owner)
curl -s -H "Authorization: Bearer $TOKEN" localhost:8100/api/v1/me | jq .

The response lists the two programs with their permissions. Development tokens are HS256 with the header kid: dev, signed with DEV_TOKEN_SECRET, and the API accepts them only when APP_ENV is dev or test. Keep the shell open; the next step needs $TOKEN.

Step 4: Run the web app in dev-identity mode

cd ../web
npm ci
cp .env.example .env.local

Edit .env.local: leave NEXT_PUBLIC_AUTH_CLIENT_ID and NEXT_PUBLIC_AUTH_AUTHORITY empty, keep NEXT_PUBLIC_API_BASE_URL=http://localhost:8100, and set NEXT_PUBLIC_DEV_TOKEN to the value of $TOKEN. Then:

npm run dev         # next dev -p 3100

Without a client id the app skips the identity provider and sends the development token as the bearer on every API call.

Step 5: Open the illustrative program

Open http://localhost:3100. The resolver reads /me, finds no last_program cookie and sends you to the first program’s home page, /p/<slug>/home. Use the program switcher in the topbar (labelled “Switch program”) to choose Illustrative program TRV-101; the URL becomes /p/trv-101/home.

The rail on the left lists Home, Evidence, Plans, Review, Progress, Console, Setup and Organization; the panel next to it lists the sections of the selected product. Choose Evidence in the rail and Questions in the panel: the illustrative questions appear, each with the “Illustrative” label.

Step 6: Start the worker (optional)

cd ../api
make worker         # two lanes: interactive (console turns) and background (sync runs, jobs, tool invocations)

With the worker running, an agent action such as Compare findings on a question is queued as an agent run and completed by the fake runtime with illustrative, agent-origin findings that a person then decides on; the Ask the agent tutorial continues from here in the console.