Requirements
The machine, the accounts and the keys, and which of them are genuinely optional.
Four things are needed to run this, and two of them are optional. The list is short on purpose: there is no message queue to operate, no worker fleet, no container registry, and no SaaS of ours in the middle.
| Needed for | Where it comes from | |
|---|---|---|
| Node 22.6 or newer | Running the app. Nothing else works without it | nodejs.org, take the LTS |
| A Convex deployment | The database, the functions, the accounts | convex.dev, free to start |
| A mail provider | Optional. Confirmation codes and resets | resend.com, or any SMTP you prefer |
| A model provider | Optional at first. Real answers | The Vercel AI Gateway, or a key from a provider you already have |
Node, and the version floor
The app is built against Node 22.6 or newer. That floor is not arbitrary: the installer scripts and the
configuration walk in scripts/ are TypeScript that Node runs directly by stripping the types, which is what
22.6 added. An older Node refuses them by name, and the installer says so rather than failing somewhere
stranger later.
Convex, which is the backend
Convex is where the schema, the functions, the scheduled work and the accounts live. It is the one
dependency that is not optional, and it is also the one that is easiest to get right: npx convex dev signs
in to your account, creates a development deployment, writes NEXT_PUBLIC_CONVEX_URL for you, and prints the
address the app needs.
You can stay on the free tier while you set everything up. Moving to a paid tier later is a change on Convex's side, not a migration in this app.
One deployment per installation, at least
A development deployment and a production deployment are two different places
with two different environments. That is deliberate and useful: try a change
against the first, then push it to the second with npx convex deploy. See
Convex, set up properly.
Resend, which is optional until somebody needs a code
Every account flow that sends mail, which is confirmation, password reset and anything the support inbox
answers with, goes through RESEND_API_KEY and EMAIL_FROM. Without them those messages are not sent, and
the app says so instead of pretending.
Two things about mail that catch people out, both of which are on the variable pages:
- The sending domain has to be verified at the provider, or the messages are refused.
EMAIL_FROMhas to be an address on that verified domain, written asName <address@domain>.
A model provider, which is optional at first
Without a model key the assistant still answers, over the real streaming path, with canned words. That is
deliberate: the whole product can be seen, clicked through and evaluated before anybody pays for tokens. The
moment you want a real answer, add a key in Intelligence → Providers & keys, or point the app at the Vercel
AI Gateway.
See Model keys.
Hosting, when you are ready
Two decisions rather than one, because the app and the backend are separate.
| Piece | Where it runs | What it needs |
|---|---|---|
| The app | Anywhere that runs Node: a small VPS, a platform, a home machine | pnpm build, then pnpm start |
| The backend | Convex's own infrastructure, pushed to with npx convex deploy | The twelve deployment variables |
There is no background worker to run, no cron of yours to configure, and no file system the app must own except the folder it lives in. Running it for real covers certificates, the reverse proxy, and the two addresses that have to be right.