Skip to content
Get packs

Guide · Open source

How to use Zero: self-host the open-source email app

Updated · written with AI from the project's own documentation and checked against our catalogue data

Zero is an open-source email app that you can self-host and connect to Gmail and other email providers. This guide walks through the local setup from the project README: installing prerequisites, starting the PostgreSQL database, configuring environment variables and Google credentials, and running the app in your browser. By the end you will know what the setup involves and what each part is for.

ZeroMail-0/Zero · ★ 10.9k · MIT

Quick start

  1. 1Check prerequisites. Install Node.js v18 or higher, pnpm v10 or higher and Docker v20 or higher.
  2. 2Clone and install. Clone the Mail-0/Zero repository and run pnpm install inside the folder.
  3. 3Start the database. Run pnpm docker:db:up to start the local PostgreSQL instance.
  4. 4Configure environment. Run pnpm nizzy env and pnpm nizzy sync, then set BETTER_AUTH_SECRET and Google OAuth values in .env.
  5. 5Create tables. Run pnpm db:push to set up the database tables.
  6. 6Start the app. Run pnpm dev and open http://localhost:3000 in your browser.

What you need before you start

Zero is set up by cloning the repository and building it yourself, so you need a few developer tools installed first. The README lists these as required versions.

  • Node.js v18 or higher
  • pnpm v10 or higher
  • Docker v20 or higher
  • Google Cloud credentials if you want Gmail integration

Clone the repository and install dependencies

Download the source code from GitHub, move into the project folder, and install its packages with pnpm.

git clone https://github.com/Mail-0/Zero.git cd Zero pnpm install

Start the local database

Zero stores data in PostgreSQL. The README provides a Docker command that starts a local instance. It creates a database named zerodotemail on port 5432 with the username and password both set to postgres, and the connection string for local development is listed in the README.

  • Name: zerodotemail
  • Username: postgres
  • Password: postgres
  • Port: 5432
  • DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"
pnpm docker:db:up

Configure environment variables

Run the nizzy command to create your .env file from the .env.example file and fill in the variables. Then set the Better Auth secret. The README suggests generating it with openssl.

Google OAuth is required for Gmail integration. In Google Cloud Console you create a project, enable the People API and Gmail API, create OAuth 2.0 credentials of the Web application type, and add the development redirect URI http://localhost:8787/api/auth/callback/google. Add yourself as a test user under Audience. The redirect URI must match exactly, including protocol, domain and path.

  • Set BETTER_AUTH_SECRET in .env to a random string
  • Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from your OAuth credentials
  • Optional: AUTUMN_SECRET_KEY, described as required for some encryption
  • Optional: Twilio values (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER) for SMS integration
pnpm nizzy env pnpm nizzy sync openssl rand -hex 32

Create the database tables and start the app

With the database running and .env filled in, push the schema to create the tables. Then start the development server. The README says the app is served at localhost port 3000 once it is running.

  • Other database commands in the README: pnpm db:generate (create migration files after schema changes), pnpm db:migrate (apply migrations), pnpm db:studio (view database content)
pnpm db:push pnpm dev

Open Zero in your browser and understand sync settings

Open http://localhost:3000 in your browser. The README also describes three sync-related environment variables. DROP_AGENT_TABLES controls whether the Durable Object drops the threads table before a sync. THREAD_SYNC_MAX_COUNT sets how many threads to sync, with a maximum of 500 per page. THREAD_SYNC_LOOP keeps syncing until a whole folder is complete and should be true in production.

  • DROP_AGENT_TABLES: drop the threads table before starting a sync
  • THREAD_SYNC_MAX_COUNT: threads per request, max 500
  • THREAD_SYNC_LOOP: sync all items in a folder until complete

What people use it for

  • Developers who want to self-host an email client and modify its code
  • Privacy-minded users who are willing to run their own server
  • Teams testing AI agents and language model features on top of email
  • People who want one inbox that combines Gmail and other providers

Frequently asked questions

Is Zero free to use?

The source material says Zero is released under the MIT licence, which is an open-source licence. It does not list prices. Third-party services you connect, such as Google Cloud, Twilio or Autumn, have their own terms, which the README links to.

What do I need to run Zero?

The README lists Node.js v18 or higher, pnpm v10 or higher and Docker v20 or higher. You also need a PostgreSQL database, which the Docker command starts locally, and Google Cloud OAuth credentials for Gmail integration.

Can Zero connect to Gmail and other email providers?

Yes. The project describes a unified inbox that connects multiple providers such as Gmail and Outlook. Gmail integration requires the Google People API and Gmail API enabled in Google Cloud and OAuth credentials in your .env file.

Why does Google sign-in fail with a redirect error?

The README warns that the authorized redirect URIs in Google Cloud Console must match exactly what is in your configuration, including protocol, domain and path. For development the URI is http://localhost:8787/api/auth/callback/google. Also make sure your email is added as a test user.

Is Zero a good alternative to Thunderbird, Mailspring or Roundcube?

Those are comparable projects, but the source does not compare them in detail. Zero's distinguishing features are its AI agents and language model integration and its unified inbox across providers. Thunderbird, Mailspring and Roundcube are established desktop or web mail clients, and the README does not say how Zero's maturity compares to them.

Is Zero ready for production use?

The source says the latest release is v0.1 and the README does not describe maturity or support levels. It is best treated as a project for development and experimentation unless you have tested it for your own needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Zero suits developers and privacy-minded users who are comfortable with Node.js, Docker and Google Cloud setup and want to self-host and modify an email client. If you want a ready-to-use mail service or a proven production system, a mature client such as Thunderbird, Mailspring or Roundcube, or a hosted provider, is a safer choice.

Install options & downloads