### Local development setup

Source: https://github.com/elie222/inbox-zero/blob/main/README.md

Commands to clone the repository, start Postgres and Redis with Docker, install dependencies, set up environment, run Prisma migrations, and start the dev server. Requires Docker, Node.js v24+, and pnpm v10+. Open http://localhost:3000 after.

```bash
git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero
docker compose -f docker-compose.dev.yml up -d   # Postgres + Redis
pnpm install
npm run setup                                     # Interactive env setup
cd apps/web && pnpm prisma migrate dev && cd ../..
pnpm dev
```

--------------------------------

### Install CLI with Homebrew

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/quick-start.mdx

Install the CLI via Homebrew, then run setup and start commands.

```bash
brew install inbox-zero/inbox-zero/inbox-zero
inbox-zero setup
inbox-zero start
```

--------------------------------

### Start the setup wizard with npx @inbox-zero/cli@latest setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/setup-cli-reference.mdx

Run the latest setup wizard interactively. The wizard asks which deployment target and providers to configure. Review generated files before committing or deploying because they can contain environment-specific values.

```bash
npx @inbox-zero/cli@latest setup
```

--------------------------------

### Manual installation and environment setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/gcp-cloudflare-tunnel.mdx

Clones the repository and prepares the environment file for manual configuration.

```bash
git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero
cp apps/web/.env.example apps/web/.env
nano apps/web/.env
```

--------------------------------

### Manual environment setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/contributing.mdx

Copies the example environment file and provides a command to generate secrets.

```bash
cp apps/web/.env.example apps/web/.env
# Generate secrets with: openssl rand -hex 32
```

--------------------------------

### Automate Setup with CLI

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/google-oauth.mdx

Use the CLI to automate API enabling and Pub/Sub setup, which also guides you through manual OAuth console steps.

```bash
inbox-zero setup-google
```

--------------------------------

### Install Node.js LTS

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/ec2-deployment.mdx

Install the Node.js LTS version using the NodeSource setup script. This is only required if you intend to use the setup CLI.

```bash
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs
```

--------------------------------

### Run interactive setup CLI

Source: https://github.com/elie222/inbox-zero/blob/main/docs/contributing.mdx

Runs the interactive setup CLI that guides through environment configuration and auto-generates secrets.

```bash
pnpm run setup
```

--------------------------------

### Start local Google emulator

Source: https://github.com/elie222/inbox-zero/blob/main/README.md

Starts the local Google emulator using Docker with the google-emulator profile. Run after pnpm install.

```bash
docker compose -f docker-compose.dev.yml --profile google-emulator up -d
```

--------------------------------

### Set up Inbox Zero via CLI

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/gcp-cloudflare-tunnel.mdx

Installs Node.js and runs the setup wizard to configure the application.

```bash
# Install Node.js (required for the setup CLI)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Run the setup wizard
npx @inbox-zero/cli setup
```

--------------------------------

### Example prompt for Azure CLI setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/teams/setup.mdx

Example prompt for an agentic coding tool to set up the Teams integration using Azure CLI. Note that browser-authenticated steps like accepting Teams channel terms and uploading the Teams app package must still be done manually.

```text
Use Azure CLI to set up the Microsoft Teams integration for Inbox Zero. Create a single-tenant Entra app registration with a client secret, create an Azure Bot resource on the F0 tier, point it at https://<your-domain>/api/teams/events, enable the Teams channel, and then tell me exactly which environment variables and manual Azure/Teams UI steps are left for me to complete.
```

--------------------------------

### Automate Google Cloud setup with CLI

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/self-hosting.mdx

Use this command to enable APIs and create Pub/Sub topics automatically. Requires the gcloud CLI to be installed.

```bash
npx @inbox-zero/cli setup-google --project-id YOUR_PROJECT_ID --domain yourdomain.com
```

--------------------------------

### Start development server

Source: https://github.com/elie222/inbox-zero/blob/main/docs/contributing.mdx

Starts the development server, making the app available at http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Setup and run commands for mail loading simulation

Source: https://github.com/elie222/inbox-zero/blob/main/apps/web/__tests__/playwright/mail-simulation/README.md

Commands to install dependencies, apply database migrations, run the mail-loading Playwright test, and execute the quota proxy unit test. Requires a disposable Postgres database; PREVIEW_DATABASE_URL_UNPOOLED takes precedence over other Prisma URLs. Supply local Redis to exercise account cooldowns; otherwise shared rate-limit protection is disabled.

```sh
pnpm install
# Use a disposable local Postgres database with this repository's migrations.
# PREVIEW_DATABASE_URL_UNPOOLED takes precedence over other Prisma URLs.
PREVIEW_DATABASE_URL_UNPOOLED="$SIMULATION_DATABASE_URL" pnpm -F inbox-zero-ai exec prisma migrate deploy
DATABASE_URL="$SIMULATION_DATABASE_URL" \
  UPSTASH_REDIS_URL="$SIMULATION_REDIS_URL" UPSTASH_REDIS_TOKEN="$SIMULATION_REDIS_TOKEN" \
  pnpm -F inbox-zero-ai test:mail-loading
node --test apps/web/__tests__/playwright/mail-simulation/quota-proxy.test.mjs
```

--------------------------------

### Quick Start Commands

Source: https://github.com/elie222/inbox-zero/blob/main/packages/cli/README.md

Configure and start Inbox Zero interactively, then open the web UI at http://localhost:3000.

```bash
# Configure Inbox Zero (interactive)
inbox-zero setup

# Start Inbox Zero
inbox-zero start

# Open http://localhost:3000
```

--------------------------------

### Show CLI help and command-specific help flags

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/setup-cli-reference.mdx

Run the CLI with --help, or a command followed by --help, to see the flags supported by the installed version. The commands cover setup for Google, AWS, Terraform, and Vercel.

```bash
npx @inbox-zero/cli@latest --help
npx @inbox-zero/cli@latest setup-google --help
npx @inbox-zero/cli@latest setup-aws --help
npx @inbox-zero/cli@latest setup-terraform --help
npx @inbox-zero/cli@latest setup-vercel --help
```

--------------------------------

### Setup Claude Code Provider

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/llm-setup.mdx

Install the required package and configure the environment to enable the experimental claude-code provider.

```bash
cd apps/web
pnpm add ai-sdk-provider-claude-code@4.3.1
claude auth login
```

```env
CLI_LLM_ENABLED=true
DEFAULT_LLMS=claude-code:sonnet
```

--------------------------------

### Setup Codex CLI Provider

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/llm-setup.mdx

Install the required packages and configure the environment to enable the experimental codex-cli provider.

```bash
cd apps/web
pnpm add ai-sdk-provider-codex-cli@1.1.0
pnpm add -g @openai/codex
codex login
```

```env
CLI_LLM_ENABLED=true
DEFAULT_LLMS=codex-cli:gpt-5.3-codex
CODEX_CLI_ALLOW_NPX=false
```

--------------------------------

### Setup Inbox Zero from cloned repository

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/self-hosting.mdx

Clone the repository and run the setup wizard to configure OAuth, AI providers, and secrets.

```bash
git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero
corepack enable
pnpm install
pnpm run setup
```

--------------------------------

### Install via Homebrew

Source: https://github.com/elie222/inbox-zero/blob/main/packages/cli/README.md

Installs the CLI using Homebrew on macOS/Linux.

```bash
brew install inbox-zero/inbox-zero/inbox-zero
```

--------------------------------

### Install Docker Compose

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/ec2-deployment.mdx

Download and install the latest version of Docker Compose as a CLI plugin, then verify the installation.

```bash
mkdir -p ~/.docker/cli-plugins
curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
# Verify it works
docker compose version
```

--------------------------------

### Run CLI setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/aws-copilot.mdx

Runs the automated Copilot setup script from the repo root. It configures addons, secrets, and deploys the environment and service.

```bash
pnpm setup-aws
```

--------------------------------

### Run Telegram Bot Setup via Shortcut

Source: https://github.com/elie222/inbox-zero/blob/main/docs/telegram/setup.mdx

A local shortcut command to execute the Telegram bot setup script.

```bash
pnpm --filter inbox-zero-ai telegram:setup
```

--------------------------------

### Deploy Webhook Gateway First-time Setup

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/aws-copilot.mdx

Follow this sequence to deploy the environment, the service, and finally the webhook gateway addon to ensure the HTTPS listener is available.

```bash
copilot env deploy --name production
```

```bash
copilot svc deploy --name inbox-zero-ecs --env production
```

```bash
cp copilot/templates/webhook-gateway.yml copilot/environments/addons/
copilot env deploy --name production
```

--------------------------------

### Local E2E Quick Start Commands

Source: https://github.com/elie222/inbox-zero/blob/main/apps/web/__tests__/e2e/flows/README.md

Standard sequence of commands to set up the environment, migrate the database, and run E2E tests.

```bash
# 1. Run setup with a named config (won't overwrite your existing .env)
npm run setup -- --name e2e

# 2. Run database migrations with the E2E env
cd apps/web
pnpm prisma:migrate:e2e

# 3. Start the dev server with E2E config
pnpm dev:e2e

# 4. OAuth your test accounts at http://localhost:3000
#    - Sign in with your Gmail test account
#    - Sign out and sign in with your Outlook test account

# 5. Add test account emails to apps/web/.env.e2e:
#    E2E_GMAIL_EMAIL="your-test@gmail.com"
#    E2E_OUTLOOK_EMAIL="your-test@outlook.com"

# 6. Run the tests (loads .env.e2e automatically)
pnpm test-e2e:flows
```

--------------------------------

### Install Cloudflared Service

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/gcp-cloudflare-tunnel.mdx

Registers cloudflared as a systemd service to ensure it starts automatically on boot.

```bash
sudo cloudflared service install <YOUR_TUNNEL_TOKEN>
```

--------------------------------

### Quick start commands

Source: https://github.com/elie222/inbox-zero/blob/main/packages/api/README.md

Basic commands to list rules and view statistics. Ensure INBOX_ZERO_API_KEY is set in your environment before execution.

```bash
inbox-zero-api rules list
inbox-zero-api stats by-period --period week
```

--------------------------------

### Install Cloudflared

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/gcp-cloudflare-tunnel.mdx

Downloads and installs the cloudflared Debian package on the VM.

```bash
# Example — copy the exact command from the Cloudflare dashboard
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
```

--------------------------------

### Deploy with terraform init and apply

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/terraform.mdx

Run these commands to initialize Terraform and apply the configuration. After apply, use terraform output service_url to get the ALB DNS name.

```bash
cd terraform
terraform init
terraform apply
```

--------------------------------

### Configure QStash Backend

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/self-hosting.mdx

Add these credentials to your .env file to enable the QStash background job backend.

```bash
QUEUE_BACKEND=qstash
QSTASH_TOKEN=your-qstash-token
QSTASH_CURRENT_SIGNING_KEY=your-signing-key
QSTASH_NEXT_SIGNING_KEY=your-next-signing-key
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/elie222/inbox-zero/blob/main/docs/contributing.mdx

Installs all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Error Response Example

Source: https://github.com/elie222/inbox-zero/blob/main/docs/api-reference/introduction.mdx

Example JSON error response structure.

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key",
    "hint": "Include a valid API-Key header. See https://docs.getinboxzero.com/api-reference/introduction."
  }
}
```

--------------------------------

### Install CLI globally with npm

Source: https://github.com/elie222/inbox-zero/blob/main/docs/api-reference/cli.mdx

Install the CLI globally using npm.

```bash
npm install -g @inbox-zero/api
```

--------------------------------

### Quick Start CLI Commands

Source: https://github.com/elie222/inbox-zero/blob/main/clawhub/inbox-zero-api/SKILL.md

Common commands for listing rules, retrieving weekly stats, and inspecting the OpenAPI schema. Use the --json flag for machine-readable output.

```bash
inbox-zero-api rules list --json
inbox-zero-api stats by-period --period week --json
inbox-zero-api openapi --json
```

--------------------------------

### Start local Microsoft emulator

Source: https://github.com/elie222/inbox-zero/blob/main/README.md

Starts the local Microsoft emulator using Docker with the microsoft-emulator profile.

```bash
docker compose -f docker-compose.dev.yml --profile microsoft-emulator up -d
```

--------------------------------

### Deploy Services with Docker Compose

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/self-hosting.mdx

Starts the application services with the specified domain using the 'all' profile.

```bash
NEXT_PUBLIC_BASE_URL=https://yourdomain.com docker compose --profile all up -d
```

--------------------------------

### Start the application with Docker Compose

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/gcp-cloudflare-tunnel.mdx

Starts the application services in detached mode using the specified base URL.

```bash
NEXT_PUBLIC_BASE_URL=https://inbox.yourdomain.com docker compose --profile all up -d
```

--------------------------------

### Start BullMQ Worker Profile

Source: https://github.com/elie222/inbox-zero/blob/main/docs/hosting/self-hosting.mdx

Use this command to start the worker process when using the BullMQ backend with Docker Compose.

```bash
docker compose --profile queue-worker up -d
```