Quick Start Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/setup-cf.js
• src/app.ts
• src/routes/setup.tsx
• src/routes/settings.tsx
• package.json
• wrangler.toml
• CONTRIBUTING.md

e-zer0 acts as a secure bridge between AI agents and email providers like Gmail and Outlook. It runs on the Cloudflare Developer Platform and uses the Model Context Protocol (MCP) to allow agents to manage emails while protecting sensitive data through PII redaction and prompt injection scans.

Sources: README.md:1-12, AGENTS.md:5-10

Local Development Setup

To run e-zer0 locally, you must configure a development environment using Node.js 22 and the Cloudflare Wrangler CLI.

Prerequisites and Installation

1. Clone the repository to your local machine.
2. Install dependencies using npm install.
3. Generate local development keys (ENCRYPTION_KEY and JWT_SECRET) by running npm run setup-cf. This script creates or updates the .dev.vars file.
4. Initialize the local database by running npm run db:migrate:local.

Sources: README.md:213-228, CONTRIBUTING.md:25-30, scripts/setup-cf.js:10-50

Running the Development Server

Execute npm run dev to start the local server at http://localhost:8787. In this mode, Turnstile bot protection is skipped.

Sources: README.md:208, scripts/setup-cf.js:220

Local Setup Workflow

The following diagram illustrates the initialization process for a local environment:

Cloudflare Deployment

e-zer0 deploys to Cloudflare Workers and utilizes D1 for storage, Vectorize for semantic search, and KV for rate limiting.

One-Click Deployment via GitHub Actions

1. Fork the e-zer0 repository.
2. In GitHub Settings > Secrets and variables > Actions, add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.
3. Add a repository variable named INSTANCE_NAME (e.g., my-e-zer0).
4. Run the Deploy e-zer0 workflow in the Actions tab.

Sources: README.md:144-165

Remote Resource Provisioning

The setup-cf.js script automates the creation of required Cloudflare resources when an API token is present.

Resource Type	Binding Name	Purpose
D1 Database	DB	Stores encrypted credentials and audit logs
Vectorize Index	VECTOR_INDEX	Enables semantic email search
KV Namespace	RATE_LIMITER	Protects login and token endpoints
Workers AI	AI	Generates text embeddings

Sources: wrangler.toml:13-33, scripts/setup-cf.js:102-140

Initial Application Configuration

After deployment or starting the local server, you must complete the first-run setup.

1. Create Admin Account

Navigate to the /setup route. You must provide a username and a password (minimum 8 characters). This account is stored in the admin_users table and manages the e-zer0 instance.

Sources: src/routes/setup.tsx:12-40, README.md:124

2. Configure OAuth Providers

Navigate to Settings to enter your OAuth credentials. This is a one-time setup required by Google and Microsoft.

• Google: Requires Gmail API, Google Tasks API, and Google Calendar API.
• Microsoft: Requires an Azure App Registration with "Any Entra ID Tenant + Personal Microsoft accounts" support.

Sources: src/routes/settings.tsx:50-280, README.md:46-54

3. Connect Email Accounts

Go to Email Accounts and click "+ Add Gmail" or "+ Add Outlook". Complete the standard provider consent screen to link your account. e-zer0 stores the resulting tokens in the encrypted D1 vault.

Sources: README.md:38-44, src/routes/settings.tsx:285-300

Developer Commands Summary

Command	Action
npm run setup-cf	Provision Cloudflare resources and generate keys
npm run db:migrate:local	Apply SQL migrations to local D1 instance
npm run check	Run Prettier, TypeScript type checking, and Vitest
npm run deploy	Deploy the application to Cloudflare production

Sources: package.json:7-25, CLAUDE.md:7-16

Summary

The Quick Start Guide facilitates the transition from a fresh repository to a functional AI-email bridge. By automating key generation and resource provisioning through setup-cf, the system ensures a secure baseline. Users first establish administrative control via the Setup wizard, then bridge to providers using the normalized OAuth configuration in the Settings module.

Sources: README.md:118-125, src/app.ts:50-65