How to Self-Host Whirl, a Full-Stack AI Chat App

What Is Whirl?

Whirl is an open-source, full-stack AI chat application built with Next.js and Convex. It is the code behind whirl.chat and is available under the MIT license, so you can inspect it, run your own instance, or contribute improvements.

The project brings multiple AI models, persistent memory, editable artifacts, web research, custom tools, and privacy-focused conversations into one interface. Models are routed through OpenRouter, while Convex provides the database, backend functions, streaming, and scheduled jobs.

Key Features

• Multiple leading models: Use top AI models in one conversation and adjust their thinking levels.
• Living artifacts: Create documents, charts, and interactive pages that remain editable in a side panel and can be shared by link.
• Tools and skills: Connect external tools through MCP, including OAuth-based integrations, and install skills that extend Whirl's behavior.
• Long-term memory: Carry preferences and project context across conversations.
• Current web information: Search the web and read pages to produce answers grounded in recent sources.
• Private conversations: Locked chats are encrypted on the user's device with a password the server never receives. They use only zero-retention models.
• Productivity features: Whirl includes incognito mode, message queueing, voice input, image generation, file attachments, folders, and sharing.
• Customizable interface: Choose light or dark mode, set accent colors, and install Whirl as a mobile web app.

Technology Stack

The production web application uses Next.js 16, React 19, Tailwind CSS v4, and Motion. Convex supplies the backend, Clerk handles authentication, and OpenRouter provides model access through the AI SDK. The repository is organized as Bun workspaces and written in TypeScript.

Only Convex, Clerk, and OpenRouter are required for the core setup. Other services are optional:

• Autumn for billing
• Exa for web search
• Supermemory for memory
• PostHog and Axiom for analytics
• Braintrust for tracing
• Resend for email
• Median for the support agent

If an optional service is not configured, Whirl hides the feature powered by that service rather than requiring it to run the application.

Prerequisites

Before installing Whirl, prepare the following:

• Bun installed on your computer
• A free Convex account
• A Clerk application
• An OpenRouter API key
• Git for cloning the repository

Step 1: Clone and Install Whirl

Clone the repository, enter its directory, and install all workspace dependencies with Bun:

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

Step 2: Create the Convex Backend

Move into the backend package and start the Convex development process:

cd packages/backend
bunx convex dev

On the first run, Convex walks you through creating a project and development deployment. Keep this process running so backend changes can be synchronized during development.

Step 3: Configure Backend Secrets

Open another terminal in packages/backend. Add the Clerk JWT issuer domain and OpenRouter API key to the Convex environment:

bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

Replace the example values with credentials from your own Clerk and OpenRouter accounts. The detailed self-hosting documentation explains the Clerk JWT template that Convex requires.

Do not commit API keys or authentication secrets to the repository. Store backend secrets through the Convex environment commands and local web settings in the appropriate environment file.

Step 4: Configure the Web Application

Move to the production web application and create a local environment file from the provided example:

cd ../../apps/v2
cp .env.example .env.local

Open .env.local and fill in the four required values for Convex and Clerk. Use the example file as the source of the exact variable names rather than creating new names.

Step 5: Start the Development Environment

Return to the repository root and start the development command:

cd ../..
bun run dev

Once the services are running, open localhost:3000. Sign in through the configured Clerk application and begin a conversation.

Basic Usage

Start a Conversation

Enter a request in the chat composer and send it to the configured model. A simple first prompt can verify that the web app, authentication, Convex backend, and OpenRouter connection are working together:

Explain the main components of this application in five concise points.

Work with Models

Whirl is designed to provide access to multiple leading models through OpenRouter within a conversation. You can also use adjustable thinking levels where supported by the application and selected model.

Create and Refine Artifacts

Ask Whirl to produce a document, chart, or interactive page. These living artifacts remain editable in a side panel and can be shared by link, making them useful for outputs that need continued refinement rather than a single chat response.

Use Files, Voice, and Organization

Whirl supports file attachments and voice input in addition to typed messages. Conversations can be organized into folders, while sharing features make selected work available to others.

Understanding the Repository

The monorepo contains several applications and a shared backend:

• apps/v2: The production Next.js web application used by Whirl.
• apps/console: A Vite-based administration console for models, integrations, and skills.
• apps/mobile: A native application built with Expo.
• apps/waitlist: A standalone waitlist page.
• apps/remotion: Promotional video compositions.
• apps/legacy: The previous web application, retained for reference but no longer maintained.
• packages/backend: The Convex schema, functions, and AI pipeline.
• docs: Self-hosting, configuration, and architecture guides.
• brand: Logos, colors, banners, and application icons.

For current web development, focus on apps/v2 and packages/backend. Avoid building new work on apps/legacy, because it is not maintained.

Advanced Tips

Add Optional Services Incrementally

Begin with the required Convex, Clerk, and OpenRouter configuration. After the core chat flow works, add optional providers one at a time. Whirl automatically hides functionality whose required keys are absent, which makes it practical to operate a smaller installation.

Consult the repository's configuration guide for the environment variables associated with billing, search, memory, analytics, tracing, email, and support.

Choose the Appropriate Privacy Mode

Use incognito mode when you do not want a normal persistent conversation workflow. For stronger protection, locked chats are encrypted on the device with a password that the server never sees and are answered only by zero-retention models. Remember that losing a client-held password may affect your ability to access encrypted content.

Inspect the Message Pipeline

When debugging streaming, tool calls, or model behavior, read the project's architecture guide. It explains how a message travels from the composer to the model and back. The relevant implementation is split primarily between the production web app and the Convex backend.

Prepare for Production Carefully

The quick start creates a development environment. Before a public deployment, follow the complete self-hosting guide, including its instructions for the Clerk JWT template and production deployment.

Contribute Safely

Before opening a pull request, review the project's contributing guide for conventions and checks. Follow the code of conduct, and report security issues using the process in SECURITY.md rather than a public issue.

Conclusion

Whirl provides a feature-rich starting point for a self-hosted AI chat workspace, combining a Next.js interface with a Convex backend, Clerk authentication, and OpenRouter model access. Start with the three required services, verify local chat at localhost:3000, and then enable optional search, memory, analytics, billing, and other integrations according to your deployment's needs.