keinsaasforever/better-chatbot

---

Deploy to Vercel

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:

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.

---

Quick start (Docker)

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 .env

POSTGRES_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-gateway

docker compose -f docker/compose.yml up -d --build

Open 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.

---

See it in action

Web search

Ask about anything current and get an answer with its sources. Needs the optional EXA_API_KEY.

Charts and tables

One sentence in, a chart or an interactive table out.

Code execution

Python and JavaScript run in a sandbox; results come back as tables and charts. Needs the optional E2B_API_KEY.

Agents

Mention an agent with @ and it takes over the conversation with its own instructions and tools.

Legal document review

An example from the agent library: paste a clause or attach a contract, and the Legal Document Reviewer flags the risks and suggests changes.

Image generation

Generate images right inside the conversation.

Tools and MCP servers

Connect your apps and any MCP server. The catalog of 250+ apps comes with the optional Composio integration.

TensorX: EU-hosted, zero data retention

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.

Local models

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.

Voice input

Click the microphone, speak, and your words are transcribed into the message box by AssemblyAI. Needs the optional ASSEMBLYAI_API_KEY.

Desktop app (beta)

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.

---

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.

Voice device. Pair an M5Stack Atom Echo S3R, press its button and talk: what you say is transcribed and handed to your agent with its tools, or turned into a new agent or a scheduled task. Pairing and device management are in the app; the device streams its audio through a small WebSocket bridge, which is not published for self-hosting yet (#429).

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.

---

Upgrading from 1.x

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 --yes

The 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.

---

Setup

Vercel

The Deploy button above. Setting up an existing clone by hand is described in docs/self-hosting.md.

Docker Compose

The quick start above. The bundled stack includes Postgres with pgvector. Add --profile redis if you want resumable chat streams.

Local development

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:3000

Postgres 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:

---

Optional integrations

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.

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"

---

Models

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.

---

Partners

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.

---

Community

• Discord — questions, help, and what people are building
• Issues — bugs and feature requests
• CONTRIBUTING.md — how to work in this repository

---

This edition, and the hosted one

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.

---

License

MIT. See LICENSE.

Originally forked from cgoinglove/better-chatbot, whose work this is built on.