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

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:

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.