Local development

Prerequisites

Optional for Phase 2+:

• Google AI (Gemini) and/or OpenAI API key
• Pusher Channels app
• GCP Pub/Sub topic + ngrok for webhooks

1. Clone and install

git clone <repo-url> commad-inbox
cd commad-inbox
bun install

This installs the root app and workspace packages (including apps/docs).

2. Environment

Copy the example env file:

cp .env.example .env.local

Fill in at minimum Phase 0 variables:

See Environment variables for the full list.

3. Database and Corsair

bun run db:migrate
bun run corsair:setup

Optional sanity check:

bun run smoke:corsair

Or run all Phase 0 steps:

bun run phase0

4. Start the dev server

bun dev

Open http://localhost:3000.

If port 3000 is busy, Next.js may use 3001 — check terminal output and match ngrok accordingly.

5. Sign in and connect

1. Sign in with Google
2. Complete Connect Google for Gmail + Calendar
3. Wait for backfill on /inbox

6. Phase 2 local webhooks (optional)

For realtime triage during development:

1. Set AI keys in .env.local
2. Configure Pub/Sub per Webhooks & realtime
3. Run ngrok: ngrok http 3000 (or 3001)
4. Set APP_URL to the ngrok HTTPS URL
5. Restart dev server

7. Documentation site

Run the Fumadocs app locally:

bun run docs:dev

Open http://localhost:3001 (docs app default port).

Build docs:

bun run docs:build

Common scripts

Full list: Scripts & CLI.

Next steps

• Corsair setup — OAuth and tenant details
• Webhooks & realtime — Pub/Sub + Pusher
• Troubleshooting