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

# Contributing

> Set up Inbox Zero for local development

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

<iframe width="560" height="315" src="https://www.youtube.com/embed/hVQENQ4WT2Y" title="Set up Inbox Zero locally" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen style={{ width: '100%', borderRadius: '0.5rem' }} />

## Prerequisites

* [Node.js](https://nodejs.org/) >= 24.0.0
* [pnpm](https://pnpm.io/) >= 10.0.0
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) (for Postgres and Redis)

## Local Development Setup

### Option A: Devcontainer

The fastest way to get started is using [devcontainers](https://containers.dev/), supported by VS Code ([Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)) 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](/hosting/setup-guides))
4. Run `pnpm dev`

### Option B: Manual Setup

1. **Start PostgreSQL and Redis:**
   ```bash theme={null}
   docker compose -f docker-compose.dev.yml up -d
   ```

2. **Install dependencies:**
   ```bash theme={null}
   pnpm install
   ```

3. **Optional: start the local Google emulator** if you want to develop against emulated Google OAuth/Gmail instead of real credentials:
   ```bash theme={null}
   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:
   ```bash theme={null}
   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:

   ```bash theme={null}
   npm run setup
   ```

   **Manual** - copy the example file and edit it yourself:

   ```bash theme={null}
   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`:

   ```bash theme={null}
   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`:

   ```bash theme={null}
   MICROSOFT_BASE_URL=http://localhost:4003
   MICROSOFT_CLIENT_ID=emulate-microsoft-client-id
   MICROSOFT_CLIENT_SECRET=emulate-microsoft-secret
   ```

6. **Run database migrations:**
   ```bash theme={null}
   cd apps/web
   pnpm prisma migrate dev
   ```

7. **Start the development server:**
   ```bash theme={null}
   pnpm dev
   ```

The app will be available at [http://localhost:3000](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](/hosting/setup-guides):

* [Google OAuth](/hosting/google-oauth)
* [Google PubSub](/hosting/google-pubsub)
* [Microsoft OAuth](/hosting/microsoft-oauth)
* [LLM](/hosting/llm-setup)

## 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:

```bash theme={null}
pnpm dev-setup init
```

Start the current branch with the saved local settings:

```bash theme={null}
pnpm dev-setup dev
```

Start with a fresh empty database instead of cloning from the main local database:

```bash theme={null}
pnpm dev-setup init --db empty
```

Run against Conductor's assigned port:

```bash theme={null}
pnpm dev-setup dev --url conductor
```

Drop the branch-local database and remove cached state when you are done:

```bash theme={null}
pnpm dev-setup clean
```

### Recommended usage

* 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:

```bash theme={null}
# 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](https://claude.ai/claude-code) or [Cursor](https://cursor.com/) and asking questions directly. The [ARCHITECTURE.md](https://github.com/elie222/inbox-zero/blob/main/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](/hosting/troubleshooting) page.

View open tasks in [GitHub Issues](https://github.com/elie222/inbox-zero/issues) and join the [Discord](https://www.getinboxzero.com/discord) to discuss what's being worked on.