Host your own ChatGPT: hands-on with Whirl, the open-source AI chat app
Every good AI chat app eventually asks for the same ransom: your chat history on someone else's servers, one vendor's models, and a subscription that climbs with your team. Whirl (whirlchat/whirl, MIT) is a different deal — the full production code behind whirl.chat, published in the open: every top model in one conversation through OpenRouter, documents and charts that stay editable in a side panel, your own tools wired in over MCP, and long-term memory that survives between chats. This walkthrough takes it from a fresh clone to a running instance on your machine in about half an hour, then shows you how to take it to production.
- Under the hood: a Bun monorepo with a Next.js 16 front end (React 19, Tailwind v4) and a Convex backend that owns the database, functions, and AI pipeline; sign-in from Clerk; every model call through OpenRouter via the AI SDK.
- You'll need Bun 1.2 or newer (npm/yarn/pnpm will not install it correctly), a free Convex account, a Clerk application, and an OpenRouter API key — the only pay-as-you-go piece.
- Clerk setup: create an application, then in Configure -> JWT templates choose New template -> Convex, keeping the name exactly "convex" — the backend only accepts tokens from a template with exactly that name (the most common self-hosting failure).
- Backend env vars on Convex: CLERK_JWT_ISSUER_DOMAIN, OPENROUTER_API_KEY, SITE_URL, and optionally MCP_ENCRYPTION_KEY for MCP integrations. Web app needs NEXT_PUBLIC_CONVEX_URL, NEXT_PUBLIC_CONVEX_SITE_URL, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY.
- bun run dev starts the web app on localhost:3000, the admin console on localhost:3001, and the Convex watcher — or run them separately with bun run dev:v2, dev:console, dev:backend.
- Optional services switch on with one key each and stay hidden until set: EXA_API_KEY (live web search + page reading), SUPERMEMORY_API_KEY (long-term memory), AUTUMN_SECRET_KEY (plans and billing). Without AUTUMN_SECRET_KEY every signed-in user gets every feature and nothing is metered — do not expose it to the open internet in that state.

Under the hood it is a Bun monorepo with a Next.js 16 front end (React 19, Tailwind v4) and a Convex backend that owns the database, the functions, and the AI pipeline. Sign-in comes from Clerk; every model call goes out through OpenRouter via the AI SDK. The design you should notice is the optionality: beyond those three, everything switches on with its own key — web search, memory, billing, analytics, tracing, email — and the features each key powers hide themselves until it is set.
What you’ll need
- Bun 1.2 or newer, plus git. Whirl is a Bun workspace; npm, yarn, and pnpm will not install it correctly, so do not try to be clever.
- A free Convex account (database, backend functions, streaming, crons).
- A Clerk application for sign-in.
- An OpenRouter API key — the only one of the three that is pay-as-you-go.
- About 30 minutes, per the self-hosting guide.
Step 1 — clone and install
git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install
That pulls the whole monorepo: the web app in apps/v2, the admin console in apps/console, an Expo mobile app, the Convex backend in packages/backend, and docs. Take a minute in docs/self-hosting.md — it is the source of truth if anything here drifts.
Step 2 — set up Clerk
- Create an application in the Clerk dashboard and turn on the sign-in methods you want (email, Google, and so on).
- Open Configure → JWT templates, choose New template → Convex, and keep the name exactly
convex. The backend only accepts tokens from a template with exactly that name — this is the single most common self-hosting failure, so double-check the spelling. - Note three values: the Frontend API URL (looks like
https://your-instance.clerk.accounts.dev), the publishable key (pk_test_...), and the secret key (sk_test_...).
Step 3 — push the backend to Convex
cd packages/backend
bunx convex dev
The first run logs you in and creates a new project plus a personal dev deployment. Then the first push stops with an error about CLERK_JWT_ISSUER_DOMAIN. That is expected: the backend cannot verify sign-ins until it knows your Clerk instance. Leave that terminal open, and in a second one set the required variables:
cd packages/backend
bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...
bunx convex env set SITE_URL http://localhost:3000
If you plan to connect integrations over MCP later, also set an encryption key for their stored credentials now:
bunx convex env set MCP_ENCRYPTION_KEY "$(openssl rand -base64 32)"
Then restart bunx convex dev in the first terminal. It pushes the backend and keeps watching packages/backend/convex for changes — leave it running. It also writes your deployment URLs to packages/backend/.env.local; you will need both in the next step:
https://<name>.convex.cloudhttps://<name>.convex.site
Step 4 — configure the web app
cd apps/v2
cp .env.example .env.local
Fill in the required block:
NEXT_PUBLIC_CONVEX_URL=https://<name>.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://<name>.convex.site
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
Step 5 — run everything
From the repository root:
bun run dev
That starts three things side by side: the web app on localhost:3000, the admin console on localhost:3001, and the Convex watcher pushing your backend. Prefer separate terminals? Use bun run dev:v2, bun run dev:console, and bun run dev:backend. Sign in, send a message, and you are up.

Step 6 — switch on the extras
Each optional service activates as soon as its key is set, and its features stay hidden until then:
# on Convex
bunx convex env set EXA_API_KEY ... # live web search + page reading
bunx convex env set SUPERMEMORY_API_KEY ... # long-term memory
bunx convex env set AUTUMN_SECRET_KEY ... # plans and billing
The billing one deserves a pause. Without AUTUMN_SECRET_KEY, every signed-in user gets every feature and nothing is metered. For a personal or team instance that is exactly what you want — and every turn still records its provider cost, so the usage tab in settings stays accurate. But do not expose the instance to the open internet in that state unless you are comfortable buying tokens for strangers.

Step 7 — make yourself admin
Admins manage the model catalog, integrations, and skills from the console (apps/console):
- Make sure your Clerk
convexJWT template includes theroleclaim from step 2:{ "role": "{{user.public_metadata.role}}" }. - In the Clerk dashboard, open your user and set public metadata to
{ "role": "admin" }. - Sign out and back in so your token picks up the claim.
- Set up the console environment (
cd apps/console && cp .env.example .env.local— same Convex URL and Clerk key as the web app) and open localhost:3001.
Step 8 — deploy to production
Backend first — create a production deployment and give it the same variables as dev, with the --prod flag:
cd packages/backend
bunx convex deploy
bunx convex env set --prod CLERK_JWT_ISSUER_DOMAIN https://clerk.your-domain
bunx convex env set --prod OPENROUTER_API_KEY sk-or-v1-...
bunx convex env set --prod SITE_URL https://your-domain
Use your Clerk production instance here (a different URL from dev) and add the same convex JWT template to it. For deploys on every push to main, add a CONVEX_DEPLOY_KEY (Convex dashboard → Settings → Deploy keys) to your GitHub repo — the included workflow .github/workflows/deploy-convex.yml picks it up automatically. The web app runs on any Next.js host: on Vercel, import the repo with the root directory set to apps/v2 and add the variables from apps/v2/.env.example with your production values.
What you built
Your own AI chat app, with a feature set that reads like a paid product’s changelog: every top model in one conversation with adjustable thinking levels; living artifacts — documents, charts, full interactive pages — that stay editable in a side panel and can be shared by link; MCP integrations with OAuth plus installable skills that teach the app new tricks; long-term memory that carries preferences and projects across chats; live web search for answers grounded in today’s web; and locked chats, encrypted on your device with a password the server never sees, answered only by zero-retention models. Incognito mode, message queueing, voice input, image generation, and file attachments are all in the box, and branding lives in one file — apps/v2/lib/site.ts — plus APP_NAME in the backend, which is the name OpenRouter shows for your traffic.
Honest limitations
- It is three managed services, not one binary. Convex and Clerk have free tiers; OpenRouter is pay-as-you-go. The software is free, the inference is metered — budget it like a utility, not a license.
- Unmetered-by-default cuts both ways. Without billing keys everyone gets everything. Perfect for personal use; a liability if you publish the URL. Autumn (or your own throttling) before you share it widely.
- Locked chats only get zero-retention models. That is the privacy guarantee working as designed, but it means the strongest models on the catalog may be unavailable in a locked chat.
- It is young. Roughly 500 stars in its first week means flags, env vars, and docs will move. Verify every command against
docs/self-hosting.mdbefore running it. - Self-hosting has known tripwires. “The server is missing part of its configuration” on every reply means
OPENROUTER_API_KEYis not set; a signed-in-but-unauthenticated state means the JWT template is not named exactlyconvex; locked chats failing to start meansNEXT_PUBLIC_CONVEX_SITE_URLis missing from the web app.
Still: there is a real gap between a ChatGPT subscription and a chat app you can read, fork, and run on your own terms — with your tools, your memory, and your models. Whirl closes it in an afternoon, and the code stays yours either way. That is worth the half hour.