Skip to content
Tinbox
Sign in

Fresh deploy — init to first sign-in

Scaffold a Tinbox project with one command, deploy it to your own Cloudflare account, and sign in for the first time — the whole path from empty folder to a working inbox.

This is the shortest path from nothing to a Tinbox inbox you can sign into. It covers the four moves in order: scaffold, deploy, sign in, and let the app tell you what's left. Everything runs on your own Cloudflare account — no mail, keys, or subscriber data ever transits a Tinbox relay.

If you'd rather not touch a terminal at all, the one-click Deploy to Cloudflare button does the scaffold and provision for you, then hands off to the same in-app onboarding at step 3.

1. Scaffold the project

tinbox init writes a small project — a worker entry, a wrangler.jsonc with the Cloudflare bindings (D1, R2, KV, Queues), and a package.json wired to the published tinbox package.

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

Try it locally before you touch a real account. This boots the worker on local SQLite, so you can sign in, read mail, and use the chat assistant against seeded data:

pnpm dev

2. Deploy to your Cloudflare account

Authenticate once — a browser login for a person, or an API token for CI/agents:

wrangler login
#   …or, for CI:  export CLOUDFLARE_API_TOKEN=…  CLOUDFLARE_ACCOUNT_ID=…

Then run one idempotent command. It provisions D1/R2/KV/Queues, generates the internal secrets, applies the baseline migrations, and deploys:

pnpm tinbox setup

setup is safe to re-run any time — it only does what's still missing. When it finishes it prints a remaining manual steps block: each account- or DNS-level step it couldn't finish (custom domain, Email Routing, sending DNS), each with the exact dashboard URL and click-path. That block is the last thing it prints, on purpose. If you authenticated with a plain wrangler login, that OAuth token lacks the Email Routing scope, so setup prints the steps instead of running them — it also prints a token guide naming the exact scopes to create a CLOUDFLARE_API_TOKEN that can finish them hands-free.

Check what's provisioned and wired at any time with the read-only health report:

pnpm tinbox doctor

Every failing or optional check in doctor prints a dashboard deep link and a numbered click-path, so nothing leaves you hunting through Cloudflare's nav.

3. Sign in for the first time

Open your deployment (the custom domain if you attached one, otherwise the *.workers.dev host the deploy printed). The first account to sign up becomes the org owner. Sign-in needs BETTER_AUTH_SECRET set — tinbox setup generates and pushes it; if you're wiring secrets by hand, set it before you sign in:

wrangler secret put BETTER_AUTH_SECRET

4. Let the app tell you what's left

Once you're in, the dashboard shows an onboarding checklist derived server-side: add a sending domain, verify its DNS, confirm inbound routing, create your first inbox, receive and send a first email, enable the assistant, invite the team. Each item has a state, a fix hint, and a deep link to the exact settings pane.

You can read the same checklist from the CLI or an agent, which is the honest source for "what's left to set up":

tinbox get-setup-state --json

Work the items top to bottom. The next three guides walk the biggest ones: Connect your domain, Your first campaign, and Connect Claude and agents.

Next steps