Quickstart Guide

This guide walks through cloning the monorepo, wiring your local environment, running migrations against MySQL, and making your first API calls.

Prerequisites

Tool	Version	Install
Node.js	20+ (LTS)	nodejs.org or `nvm install 20`
pnpm	10+	`npm install -g pnpm@10`
Wrangler CLI	4+	`npm install -g wrangler`
MySQL	8.0+ (Vitess)	PlanetScale or local MySQL

Step 1 — Clone and Install

git clone https://github.com/openinsure/openinsure
cd openinsure
pnpm install

Step 2 — Configure Environment Variables

Copy root env:

cp .env.example .env

Set these first:

Variable	Description
`DATABASE_URL`	PlanetScale URL used by Drizzle migrations
`JWT_SECRET`	API JWT signing secret
`API_SECRET`	System bearer secret (machine/demo flows)
`SERVICE_SECRET`	Service token exchange secret
`PORTAL_SECRET`	Producer portal token exchange secret
`ADMIN_SECRET`	Admin token exchange secret
`CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN`	Required for Wrangler and deploy tooling

Auth Worker:

Variable	Description
`AUTH_URL`	Auth Worker base URL (e.g., `https://auth-dev.openinsure.dev`)

Step 3 — Configure API Worker Vars

cp apps/api/.dev.vars.example apps/api/.dev.vars

Set .dev.vars values to match your .env (especially API_SECRET, JWT_SECRET, and DB connection settings).

Step 4 — Apply Database Migrations

pnpm --filter @openinsure/db db:migrate

This runs the squashed bootstrap + forward Drizzle migrations against DATABASE_URL.

Step 5 — Seed Base Rating Data (Optional but Recommended)

pnpm db:seed:rating

Step 6 — Start the Stack

pnpm dev

Common local endpoints:

App	URL
API Worker	`http://localhost:8787`
Underwriting App	`http://localhost:3000`
Producer Portal	`http://localhost:3001`
Admin	`http://localhost:3002`
Policyholder Portal	`http://localhost:3003`
Astro Docs	`http://localhost:4321`

Step 7 — Get an API JWT

For local/demo flows, exchange API_SECRET for a short-lived superadmin JWT:

curl -s -X POST http://localhost:8787/auth/demo \
  -H "Content-Type: application/json" \
  -d '{"secret":"'"$API_SECRET"'"}' | jq -r '.token'

Export token:

export TOKEN="<paste-token>"

Step 8 — First API Call

curl -s -X POST http://localhost:8787/v1/submissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "insuredName": "Pacific Coast Roofing LLC",
    "naicsCode": "238160",
    "annualRevenue": 2500000,
    "requestedLimit": 1000000,
    "requestedDeductible": 5000,
    "effectiveDate": "2026-06-01",
    "expirationDate": "2027-06-01",
    "state": "CA",
    "lineOfBusiness": "GL"
  }' | jq '.'

Next Steps

Architecture

Understand the edge/origin split, HIPAA boundaries, and multi-tenant controls.

API Reference

Explore the live Scalar docs and full OpenAPI coverage.

Policy Lifecycle

Review issuance, endorsements, cancellation, and renewal flows.

MGA Ops

Configure delegated authority, producer management, and bordereaux reporting.