Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getinboxzero.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide is for developers who want to run Inbox Zero locally and contribute to the project.

​
Prerequisites

​
Local Development Setup

​
Option A: Devcontainer

The fastest way to get started is using devcontainers, supported by VS Code (Dev Containers extension) and JetBrains IDEs:
  1. Open the project and select “Reopen in Container” when prompted
  2. Wait for the container to build and postCreateCommand to complete
  3. Configure at least one OAuth provider in apps/web/.env (see Setup Guides)
  4. Run pnpm dev

​
Option B: Manual Setup

  1. Start PostgreSQL and Redis: 
    docker compose -f docker-compose.dev.yml up -d
  2. Install dependencies: 
    pnpm install
  3. Optional: start the local Google emulator if you want to develop against emulated Google OAuth/Gmail instead of real credentials: 
    docker compose -f docker-compose.dev.yml --profile google-emulator up -d
  4. Optional: start the local Microsoft emulator if you want to develop against emulated Microsoft OAuth/Graph instead of real credentials: 
    docker compose -f docker-compose.dev.yml --profile microsoft-emulator up -d
  5. Set up environment variables using one of these methods: Interactive CLI (recommended) - guides you through each step and auto-generates secrets: 
    npm run setup
    Manual - copy the example file and edit it yourself: 
    cp apps/web/.env.example apps/web/.env
# Generate secrets with: openssl rand -hex 32
    To use the local Google emulator, set these values in apps/web/.env: 
    GOOGLE_BASE_URL=http://localhost:4002
GOOGLE_CLIENT_ID=emulate-google-client.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=emulate-google-secret
    To use the local Microsoft emulator, set these values in apps/web/.env: 
    MICROSOFT_BASE_URL=http://localhost:4003
MICROSOFT_CLIENT_ID=emulate-microsoft-client-id
MICROSOFT_CLIENT_SECRET=emulate-microsoft-secret
  6. Run database migrations: 
    cd apps/web
pnpm prisma migrate dev
  7. Start the development server: 
    pnpm dev
The app will be available at http://localhost:3000.

​
Configuration

You’ll need to configure at least one OAuth provider and an AI provider. The setup CLI handles this interactively, but for manual configuration see the Setup Guides:

​
Parallel Branch Development

If you regularly work in multiple Git worktrees or branch-specific local copies, use the dev setup helper instead of reusing a single shared app/database setup.

​
Why this helps

  • Each branch gets its own local Postgres database, so schema changes on one branch do not break another branch.
  • The helper picks a branch-specific app port, which makes it easier to run multiple local copies at once.
  • It can start local Postgres and Redis automatically when they are not already running.
  • It wires emulator-based Google and Microsoft auth for local development, which is useful when you do not want to depend on real OAuth callbacks during day-to-day work.

​
Shared env files

The helper expects shared local env files in ~/.config/inbox-zero and symlinks them into apps/web:
  • ~/.config/inbox-zero/.env.local
  • ~/.config/inbox-zero/.env.test
  • ~/.config/inbox-zero/.env.e2e
This keeps secrets in one place while still letting each branch use its own derived runtime values, such as database name and local port.

​
Common commands

Initialize the current branch for local development: 
pnpm dev-setup init
Start the current branch with the saved local settings: 
pnpm dev-setup dev
Start with a fresh empty database instead of cloning from the main local database: 
pnpm dev-setup init --db empty
Run against Conductor’s assigned port: 
pnpm dev-setup dev --url conductor
Drop the branch-local database and remove cached state when you are done: 
pnpm dev-setup clean
  • Use clone-main mode when you want realistic local data and faster setup.
  • Use empty mode when you are working on schema changes or want a clean migration path.
  • Use emulator auth for most local development.
  • Reserve real OAuth flows for cases where you specifically need to test real provider behavior.

​
Local Production Build

To test a production build locally: 
# Without Docker
pnpm run build
pnpm start --filter=web

# With Docker (includes Postgres and Redis)
NEXT_PUBLIC_BASE_URL=http://localhost:3000 docker compose --profile all up --build

​
Finding Your Way Around

To understand the codebase, we recommend connecting the repo to an AI coding tool like Claude Code or Cursor and asking questions directly. The ARCHITECTURE.md file provides a high-level overview, though it may not reflect recent changes. For troubleshooting common issues (rate limiting, OAuth errors, etc.), see the Troubleshooting page. View open tasks in GitHub Issues and join the Discord to discuss what’s being worked on.