inbox-zero Documentation

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

11,883 stars TypeScript TypeScript 1 file · ~1,832 tokens #ai#email#gmail#loops#nextjs#openai#postgresql#posthog
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy inbox-zero on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name inbox-zero -p 3000:3000 --restart always postgres:16
Configured Services & Ports
⚙️ app
image: ${FULL_IMAGE:-ghcr.io/your-username/inbox-zero}:latest
🔌 Ports: 3000:3000
⚙️ db
image: postgres:16
🔌 Ports: 5432:5432
⚙️ redis
image: redis:7
🔌 Ports: 6379:6379
⚙️ redis-http
image: hiett/serverless-redis-http:latest
🔌 Ports: 8079:80
docker-compose.yml
yaml (docker-compose.yml) 
# docker-compose.local.yml - Run locally built inbox-zero image with dependencies
#
# Usage:
#   pnpm docker:local:run                    # uses this file automatically
#   docker compose -f docker/docker-compose.prod.yml up
#
# Prerequisites:
#   1. Build the image first: pnpm docker:local:build
#   2. Configure apps/web/.env with your API keys
#
# Environment variables:
#   GITHUB_USERNAME - Your GitHub username (auto-detected from gh CLI)
#   FULL_IMAGE      - Full image path (auto-set by run-local.sh)
#

services:
  app:
    image: ${FULL_IMAGE:-ghcr.io/your-username/inbox-zero}:latest
    ports:
      - "3000:3000"
    env_file:
      - ../apps/web/.env
    environment:
      # Override database URLs to use local containers
      DATABASE_URL: postgresql://postgres:password@db:5432/inboxzero?schema=public
      DIRECT_URL: postgresql://postgres:password@db:5432/inboxzero?schema=public
      REDIS_URL: redis://redis:6379
      REDIS_HTTP_URL: http://redis-http:80
      REDIS_HTTP_TOKEN: dev_token
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: inboxzero
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    volumes:
      - redis-data:/data
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Redis HTTP interface (Upstash REST protocol)
  redis-http:
    image: hiett/serverless-redis-http:latest
    environment:
      SRH_MODE: env
      SRH_TOKEN: dev_token
      SRH_CONNECTION_STRING: "redis://redis:6379"
    ports:
      - "8079:80"
    depends_on:
      redis:
        condition: service_healthy

volumes:
  postgres-data:
  redis-data:

File: README.md

Mission

To help you spend less time in your inbox, so you can focus on what matters most.

Features

  • AI Personal Assistant: Organizes your inbox and pre-drafts replies in your tone and style.
  • AI Rules for email: Explain in plain English how your AI should handle your inbox.
  • Reply Zero: Track emails to reply to and those awaiting responses.
  • Bulk Unsubscriber: One-click unsubscribe and archive emails you never read.
  • Bulk Archiver: Clean up your inbox by bulk archiving old emails.
  • Cold Email Blocker: Auto‑block cold emails.
  • Email Analytics: Track your activity and trends over time.
  • Meeting Briefs: Get personalized briefings before every meeting, pulling context from your email and calendar.
  • Smart Filing: Automatically save email attachments to Google Drive or OneDrive.
  • Slack & Telegram Integration: Chat with your AI assistant from Slack or Telegram to manage your inbox without leaving the apps you already use.

Learn more in our docs.

Feature Screenshots

AI Assistant Reply Zero
Gmail client Bulk Unsubscriber

Demo Video

Built with

Star History

Feature Requests

To request a feature open a GitHub issue, or join our Discord.

Getting Started

We offer a hosted version of Inbox Zero at getinboxzero.com.

Self-Hosting

The fastest way to self-host Inbox Zero is with the CLI:

Prerequisites: Docker and Node.js v24+

bash
npx @inbox-zero/cli setup      # One-time setup wizard
npx @inbox-zero/cli start      # Start containers

Open http://localhost:3000

For complete self-hosting instructions, production deployment, OAuth setup, and configuration options, see our Self-Hosting Docs.

Local Development

Prerequisites: Docker, Node.js v24+, and pnpm v10+

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

Open http://localhost:3000

After pnpm install, if you want to use the local Google emulator, start it with:

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

Then point apps/web/.env at it with:

bash
GOOGLE_BASE_URL=http://localhost:4002
GOOGLE_CLIENT_ID=emulate-google-client.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=emulate-google-secret

If you want to use the local Microsoft emulator, start it with:

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

Then point apps/web/.env at it with:

bash
MICROSOFT_BASE_URL=http://localhost:4003
MICROSOFT_CLIENT_ID=emulate-microsoft-client-id
MICROSOFT_CLIENT_SECRET=emulate-microsoft-secret

See the Contributing Guide for more details including devcontainer setup.

Contributing

View open tasks in GitHub Issues and join our Discord to discuss what's being worked on.

Docker images are automatically built on every push to main and tagged with the commit SHA (e.g., elie222/inbox-zero:abc1234). The latest tag always points to the most recent main build. Formal releases use version tags (e.g., v2.26.0).

File: packages/tinybird-ai-analytics/README.md

Tinybird AI Analytics

This package contains the TypeScript client for publishing and querying AI
analytics. The Tinybird data sources and endpoints are part of the canonical
Forward project documented in ../tinybird.

Run all Tinybird CLI commands from packages/tinybird/project so the complete
workspace is validated and deployed together.

AI Cost Fields

  • cost: platform-paid estimated cost from our local pricing table (user API key traffic is 0)
  • estimatedCost: estimated cost regardless of who paid, from our local pricing table
  • providerReportedCost: exact provider-reported cost when available
  • providerUpstreamInferenceCost: exact upstream provider cost when available
  • providerCostSource: internal source key describing how provider-side cost was derived
  • isUserApiKey: 1 for user-provided API keys, 0 for platform keys
  • stepCount: total number of steps reported by the AI SDK result
  • toolCallCount: total number of tool calls across all reported steps
  • Legacy rows (before this schema change) have NULL for estimatedCost and isUserApiKey

File: packages/tinybird/README.md

Tinybird

The project directory is the canonical Tinybird Forward project
for the InboxZero workspace. It contains all analytics resources, including
the AI analytics resources consumed by @inboxzero/tinybird-ai-analytics.

CLI setup

Run the current Forward CLI without conflicting with a Classic CLI already on
your PATH:

sh
uvx --from tinybird@latest tb --version

Authenticate and select the production workspace:

sh
cd packages/tinybird/project
uvx --from tinybird@latest tb login --host https://api.us-east.tinybird.co --workspace InboxZero

Development workflow

Pull the current cloud definitions:

sh
uvx --from tinybird@latest tb --cloud pull

Start Tinybird Local and validate the project locally:

sh
uvx --from tinybird@latest tb local start
uvx --from tinybird@latest tb build
uvx --from tinybird@latest tb test run

Validate and deploy the project to Tinybird Cloud:

sh
uvx --from tinybird@latest tb --cloud deploy --check

Tinybird Forward deployments replace the Classic tb push workflow. Keep
resource definitions and TOKEN directives in packages/tinybird/project so
deployments remain reproducible from Git.

File: packages/resend/README.md

Email updates

This package is used to send transactional emails to users.

Running locally

To run:

bash
pnpm dev

Then visit http://localhost:3010/ to view email previews.

File: packages/loops/README.md

Loops Package

This package contains the code for the Loops which is used to send marketing emails to users.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #email Browse email catalog → #gmail Browse gmail catalog → #loops Browse loops catalog → #nextjs Browse nextjs catalog → #openai Browse openai catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →