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

​
Prerequisites

ToolVersionInstall
Node.js20+ (LTS)nodejs.org or nvm install 20
pnpm10+npm install -g pnpm@10
Wrangler CLI4+npm install -g wrangler
MySQL8.0+ (Vitess)PlanetScale or local MySQL
:::note OpenInsure uses PlanetScale (Vitess 22.0) as the system of record. For local dev, set DATABASE_URL to any reachable MySQL instance (PlanetScale branch 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:
VariableDescription
DATABASE_URLPlanetScale URL used by Drizzle migrations
JWT_SECRETAPI JWT signing secret
API_SECRETSystem bearer secret (machine/demo flows)
SERVICE_SECRETService token exchange secret
PORTAL_SECRETProducer portal token exchange secret
ADMIN_SECRETAdmin token exchange secret
CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKENRequired for Wrangler and deploy tooling
Auth Worker:
VariableDescription
AUTH_URLAuth 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. 
pnpm db:seed:rating

​
Step 6 — Start the Stack

pnpm dev
Common local endpoints:
AppURL
API Workerhttp://localhost:8787
Underwriting Apphttp://localhost:3000
Producer Portalhttp://localhost:3001
Adminhttp://localhost:3002
Policyholder Portalhttp://localhost:3003
Astro Docshttp://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.