Skip to main content
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:
  2. Install dependencies:
  3. Optional: start the local Google emulator if you want to develop against emulated Google OAuth/Gmail instead of real credentials:
  4. Optional: start the local Microsoft emulator if you want to develop against emulated Microsoft OAuth/Graph instead of real credentials:
  5. Set up environment variables using one of these methods: Interactive CLI (recommended) - guides you through each step and auto-generates secrets:
    Manual - copy the example file and edit it yourself:
    To use the local Google emulator, set these values in apps/web/.env:
    To use the local Microsoft emulator, set these values in apps/web/.env:
  6. Run database migrations:
  7. Start the development server:
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:
Start the current branch with the saved local settings:
Start with a fresh empty database instead of cloning from the main local database:
Run against Conductor’s assigned port:
Drop the branch-local database and remove cached state when you are done:
  • 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:

​
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. Treat the code, schemas, and tests as the source of truth for how features work. 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.