Skip to content
Tinbox
Sign in

Install Tinbox

Scaffold a new Tinbox deployment with one command and run it locally.

Tinbox ships as an npm package that scaffolds a self-contained email stack you deploy to your own Cloudflare account — inbox, transactional sending, and newsletters, with no third-party relay in the path.

Optional, for a fully hands-free setup: create a Cloudflare custom API token before step 1. Wrangler's browser login can provision and deploy Workers, but Cloudflare's Email Routing and Email Sending APIs require a token. Grant Account → Workers Scripts, D1, Workers KV Storage, R2 Storage, Queues, and Email Sending (Edit), plus Zone → Zone (Read), DNS (Edit), and Email Routing Rules (Edit), then export CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Without it, setup remains safe and prints the exact dashboard click-paths for the email-plane steps.

Scaffold a project

npx tinbox init acme.dev
cd tinbox-acme
pnpm install

tinbox init <domain> writes a worker entry (src/worker.ts), a wrangler.jsonc with the Cloudflare bindings (D1, R2, KV, Queues), and a package.json wired to the published tinbox package.

Run it locally

pnpm dev

This boots the worker on local SQLite so you can sign in, read mail, and try the chat assistant before touching a real Cloudflare account.

Choose how to deploy

There are two supported ways to put Tinbox on your Cloudflare account. Pick the zero-terminal Cloudflare button or the local, one-command CLI path.

Deploy step① Button (one-click)② CLI tinbox setup
CF account + auth✅ dashboard OAuth⚠️ wrangler login / token
Provision D1/R2/KV/Queues✅ button provisions all (incl. queues/DOs)✅ tinbox setup
Migrations (baseline schema)⚠️ via deploy script — verify ordering✅ tinbox setup/migrate
Internal secrets (BETTER_AUTH_SECRET, ASSET_SIGNING_KEY)⚠️ deploy-form prompt or script-gen✅ auto-generated
External secrets (AI key, GitHub OAuth)✅ deploy-form prompt⚠️ interactive prompt
Deploy worker✅✅ --deploy
Custom domain (mail.<domain> default, inbox.<domain> fallback)❌ manual (deploys to workers.dev)⚠️ wrangler route if zone on acct
Inbound Email Routing (catch-all → worker)❌ in-app onboarding✅ with token (else prints steps)
Sending DNS (SPF/DKIM/DMARC)❌ manual⚠️ prints; auto if DNS on CF + token
SSO "Continue with Tinbox"❌ in-app✅ domain proof

✅ automated · ⚠️ one conditional step · ❌ done by hand — the in-app onboarding (Settings → Domains) walks you through the ❌ rows after deploy.

The deploy guide has the full walkthrough for each path, with the dashboard and CLI steps for everything in the ⚠️/❌ rows.

Next steps