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: 
    docker compose -f docker-compose.dev.yml up -d
  2. Install dependencies: 
    pnpm install
  3. 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
  4. Run database migrations: 
    cd apps/web
pnpm prisma migrate dev
  5. 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:

​
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.