formerly better-chatbot
An open-source AI chat and agent platform you can host yourself.
Talk to any model, attach your files, connect MCP tool servers, build workflows, and give agents a place to work — on infrastructure you control.
Two required values, a few optional ones. The button clones the repository, creates a free Supabase project for the database and file uploads, and asks for:
| Variable | |
|---|---|
BETTER_AUTH_SECRET |
Required. Any long random string (openssl rand -base64 32). |
AI_GATEWAY_API_KEY |
Required. From vercel.com/ai-gateway. Serves every model in the catalog, including realtime voice. |
COMPOSIO_API_KEY |
Optional. Lets users connect Gmail, Slack, GitHub and more. Free key |
TENSORX_API_KEY |
Optional. EU-hosted models from our partner TensorX. |
ASSEMBLYAI_API_KEY |
Optional. Voice transcription via AssemblyAI. |
EXA_API_KEY |
Optional. Web search via Exa. |
E2B_API_KEY |
Optional. Sandboxes that run generated code, via E2B. Without it, code runs in the browser. |
INNGEST_EVENT_KEY, INNGEST_SIGNING_KEY |
Optional. Scheduled agents and background jobs, via Inngest. Easiest: add the Inngest integration in Vercel, which sets both and connects the app. |
The optional fields are pre-filled with optional; leave them like that and the
feature stays off. You can add any key later under Settings → Environment
Variables and redeploy. The database schema and the storage buckets are
created during the build. Open the deployment and create an account; the first
one becomes the administrator.
Free Supabase projects pause after a week without use. If your app stops loading after a quiet week, open the project in the Supabase dashboard and click Restore.
Updates come to you. After your first sign-in, the app asks once to Turn on automatic updates: it opens GitHub with the update check ready, and you click Commit changes. From then on your copy checks every week. When there is a new version, GitHub emails you a short guide: try the preview Vercel builds, then click Merge. Nothing changes in your live app until you do.
Details and optional features: docs/self-hosting.md.
Three variables. That is the whole configuration to get chatting:
git clone https://github.com/keinsaasforever/better-chatbot.git
cd better-chatbot
cp .env.example .envPOSTGRES_URL=postgres://postgres:postgres@postgres:5432/better_chatbot
BETTER_AUTH_SECRET= # npx @better-auth/cli@latest secret
AI_GATEWAY_API_KEY= # https://vercel.com/ai-gatewaydocker compose -f docker/compose.yml up -d --buildOpen http://localhost:3000 and create an account. The first account becomes the administrator.
Why one model key? Models are served through the Vercel AI Gateway, which fronts Anthropic, OpenAI, Google, Mistral, xAI, DeepSeek, Moonshot and more. You manage one key and one bill instead of seven, and you can switch models mid-conversation without touching configuration. If you would rather not use a gateway at all, point the app at Ollama, LM Studio, or any OpenAI-compatible endpoint — see Models.
Prefer running it directly? See docs/self-hosting.md.
Ask about anything current and get an answer with its sources. Needs the optional EXA_API_KEY.
One sentence in, a chart or an interactive table out.
Python and JavaScript run in a sandbox; results come back as tables and charts. Needs the optional E2B_API_KEY.
Mention an agent with @ and it takes over the conversation with its own instructions and tools.
An example from the agent library: paste a clause or attach a contract, and the Legal Document Reviewer flags the risks and suggests changes.
Generate images right inside the conversation.
Connect your apps and any MCP server. The catalog of 250+ apps comes with the optional Composio integration.
Pick a model under TensorX (0 Data Retention) and your prompts go straight to EU infrastructure that keeps nothing. Needs the optional TENSORX_API_KEY; see Partners.
At the end of the model menu, Add local Model connects Ollama, LM Studio or any OpenAI-compatible server. Your data stays on your hardware.
Click the microphone, speak, and your words are transcribed into the message box by AssemblyAI. Needs the optional ASSEMBLYAI_API_KEY.
The keinsaas Navigator desktop app for Windows and macOS, with local (stdio) MCP servers and native notifications. It connects to the cloud or to your own instance; see What you get.
Chat that does things. Streaming conversations with tool calling, file
attachments, image generation, and a sandboxed code runner. Mention an agent,
workflow, or tool with @ to pull it into the conversation.
Agents. Give an agent a role, instructions, and a set of tools. Share it with your workspace or keep it private.
Skills. Reusable capabilities an agent loads on demand, so a large toolbox does not have to sit in every prompt.
Projects with retrieval. Group chats, documents, and tools around a piece of work. Uploaded documents are chunked, embedded, and searched with pgvector — no external service required. Point a project at a knowledge base if you want hosted retrieval instead.
Workflows. Build a graph of steps — LLM calls, conditions, HTTP requests, code, templates — in a visual editor, publish it as a tool, and call it from any chat.
MCP tool servers. Connect any Model Context Protocol server over HTTP or stdio, with OAuth support, per-tool customization and a cached tool list. Self-hosted instances can run stdio servers; the desktop app runs them locally.
Scheduled tasks. Have an agent run on a schedule and report back.
Voice. Realtime voice conversations through the gateway, plus transcription.
Desktop app (beta for self-hosting). The keinsaas Navigator desktop app
(download at keinsaas.com) adds local (stdio) MCP servers, which a server on Vercel cannot run, plus
native notifications. On first launch it asks where to connect: pick My own
server and enter your instance's address, e.g. https://my-chatbot.vercel.app.
Connecting it to a self-hosted instance is in beta; tell us in
Discord what works and what does not. You can
switch servers any time under Change Server… in the app menu.
Model routing. Pick a model per message, or let the router choose from the catalog based on the task.
This is a new major version. The layout is now a monorepo, the environment is different, and the schema has moved on considerably.
Back up your database first. Then:
pnpm install
pnpm tsx scripts/upgrade/from-better-chatbot-1.ts --dry-run
pnpm tsx scripts/upgrade/from-better-chatbot-1.ts --yesThe upgrade preserves your users, chats, agents, MCP servers and workflows. Archives become projects, and the threads inside them stay linked. It is a one-way migration — this is why the backup matters.
If you were setting per-provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY
and friends), replace them with a single AI_GATEWAY_API_KEY, or configure a
local provider.
The Deploy button above. Setting up an existing clone by hand is described in docs/self-hosting.md.
The quick start above. The bundled stack includes Postgres with
pgvector. Add --profile redis if you want resumable chat streams.
pnpm install # writes .env from .env.example
pnpm docker:pg # Postgres with pgvector on :5432
pnpm db:migrate # apply the schema
pnpm dev # http://localhost:3000Postgres must have the pgvector extension — document embeddings are stored
as vector(1536). The bundled image has it; managed Postgres usually offers it
as a toggle.
Useful commands:
| Command | What it does |
|---|---|
pnpm check |
Lint, typecheck and unit tests — run before committing |
pnpm test:e2e |
Playwright end-to-end tests |
pnpm db:migrate |
Apply pending migrations |
pnpm db:studio |
Browse the database |
pnpm docker:redis |
Redis for resumable streams |
Everything below is off until you configure it, except file uploads on Vercel, which the Supabase integration sets up for you. The server prints which features are disabled at startup, so you always know why something is missing.
| Feature | Set | Without it |
|---|---|---|
| File uploads | Nothing on Vercel: the Supabase integration sets it. Docker and local: SUPABASE_URL, NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY (details) |
Attachments, avatars and generated images are disabled |
| Knowledge bases | AGENTSET_API_KEY |
Knowledge bases unavailable; project documents still search locally with pgvector |
| Background jobs | INNGEST_SIGNING_KEY, INNGEST_EVENT_KEY |
Scheduled tasks need your own cron (see below); the project brain runs right after each change instead of in the background |
| Resumable streams | REDIS_URL |
A stream ends when the viewer navigates away |
| Code sandbox | E2B_API_KEY |
Generated code runs in the in-browser worker only |
| Web search | EXA_API_KEY |
The web search tool is unavailable |
| EU-hosted models | TENSORX_API_KEY |
TensorX models (zero data retention) do not appear in the model picker |
| Voice transcription | ASSEMBLYAI_API_KEY |
Realtime voice still works; transcription does not |
| Browser notifications | NEXT_PUBLIC_VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY |
No notifications while the app is closed |
| Connected apps | COMPOSIO_API_KEY |
Users cannot connect Gmail, Slack, GitHub and other apps |
| Observability | SUPERLOG_PUBLIC_TOKEN |
Traces and logs stay local |
Running without Inngest. Scheduled tasks and the sandbox reaper are plain
HTTP endpoints. Set SCHEDULED_TASK_SECRET and call them from any cron:
curl -X POST https://your-instance/api/scheduled-tasks/cron \
-H "X-Scheduled-Task-Auth: $SCHEDULED_TASK_SECRET"The gateway is the default and covers the whole catalog. You can also:
- Run models locally. Connect Ollama, LM Studio, or any OpenAI-compatible endpoint from the model picker. Nothing leaves your machine, and it needs no server configuration — each account sets up its own.
- Use TensorX. EU-hosted inference with zero data retention,
reached directly rather than through the gateway. Set
TENSORX_API_KEY. - Add any OpenAI-compatible provider with
OPENAI_COMPATIBLE_DATA:pnpm openai-compatiable:init && pnpm openai-compatiable:parse.
TensorX — EU-hosted model inference with zero data
retention. The Community Edition talks to TensorX directly rather than through a
gateway, so prompts go straight to TensorX's EU infrastructure. Create a key at
tensorx.ai, set TENSORX_API_KEY, and its models appear
in the model picker next to the gateway's. See its
trust and security page and
DPA.
TensorX is optional. Without the key everything else works as before.
- Discord — questions, help, and what people are building
- Issues — bugs and feature requests
- CONTRIBUTING.md — how to work in this repository
This repository is the Community Edition of keinsaas Navigator, formerly known as better-chatbot. The repository keeps its name, so existing links, forks and automatic updates keep working. Everything above is here, in full, with no usage caps and no telemetry.
What Navigator adds is what teams need and single users do not: shared team workspaces with member management and invitations, per-member AI budgets and org-wide model policy, billing, a managed workflow builder, and a Slack bot. If you are running this for yourself or a small group, you are not missing anything — that is the point.
MIT. See LICENSE.
Originally forked from cgoinglove/better-chatbot, whose work this is built on.
