Quick Start#

Install dependencies#

bun install
bun run version:write

Prepare local environment files#

cp apps/api-worker/.dev.vars.example apps/api-worker/.dev.vars
cp apps/web/.env.example apps/web/.env

Minimum variables:

• apps/api-worker/.dev.vars
  • SESSION_SECRET
  • BOOTSTRAP_ADMIN_INVITE_CODE (optional; only if you want an empty local database to bootstrap the first admin via invite)
  • WEB_APP_ORIGIN (required for browser passkeys; it provides the primary trusted WebAuthn origin and the RP ID when you only keep one origin, and local passkey development must use http://localhost:4173 instead of an IP literal)
  • WEB_APP_ORIGINS (optional; add it when multiple production control-plane aliases must stay trusted for passkeys and need one shared non-public RP ID suffix)
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET (optional; enables GitHub login)
  • LINUXDO_CLIENT_ID / LINUXDO_CLIENT_SECRET (optional; enables LinuxDO login)
• apps/web/.env
  • VITE_API_BASE_URL

Start the Worker API and control plane#

WORKER_PORT=8787 bun run --cwd apps/api-worker dev
PORT=4173 bun run --cwd apps/web dev

Start public docs and Storybook#

DOCS_PORT=56007 bun run --cwd docs-site dev
STORYBOOK_PORT=6006 bun run --cwd apps/web storybook

Local URLs#

• Control plane: http://localhost:4173
• Worker API: http://localhost:8787
• Public docs: http://localhost:56007
• Storybook: http://localhost:6006

Login options#

• Third-party sign-in and registration now converge on /login
• Passkey first-time registration requires an invite, while linked passkeys can sign in directly afterward
• Automation and recovery flows should keep using API Keys
• When you validate passkeys locally, open the control plane from localhost instead of 127.0.0.1

Production surfaces#

• Cloudflare Workers: API Worker and inbound email Worker
• Cloudflare Pages: authenticated control plane
• GitHub Pages: public docs and Storybook

Related pages#

• Cloudflare Token Permissions
• Deployment & Environment
• Domain Catalog & Enablement