Skip to content
DeskbellGitHub

The open-source answer engine for your docs

Deskbell answers your users’ questions from your docs, with a source on every answer and a refusal when the docs don’t say. Self-hosted, any model, your brand. Built for devtools and B2B SaaS teams with public documentation.

Run the quickstartStar on GitHub

Free to self-host · AGPL-3.0 core, MIT widget

How it works

From a docs URL to a cited answer

  1. 1

    Add your docs

    Paste a URL on the Sources page. Deskbell reads the sitemap, respects robots.txt, then crawls, chunks and embeds into Postgres.

    Dashboard → Sources

    https://docs.your-product.com

  2. 2

    Pick a model

    One variable for answering, one for embeddings. Switching providers changes nothing else in the deployment.

    .env

    DESKBELL_CHAT_MODEL=anthropic/claude-sonnet-5
DESKBELL_EMBEDDING_MODEL=openai/text-embedding-3-small

  3. 3

    Add one script tag

    Served from your own deployment. The widget renders in a shadow root, so it inherits nothing from your CSS and leaks nothing into it.

    your docs template

    <script async src="https://deskbell.your-product.com/deskbell.js" data-project-key="pk_live_…"></script>

    Every attribute, with defaults

Features

What it does

A citation for every answer

The model names the chunks it used; only those become citations, each linked to the page it came from.

A refusal when the docs don't say

No answer in the retrieved context means a refusal, not prose. What was retrieved is kept, so you can see why.

The questions your docs can't answer

Unanswered, downvoted and weakly answered questions, clustered by meaning, with a trend against the previous period. Write the missing answer in the dashboard and it is indexed and cited like a page.

An eval harness that runs in CI

Recall, precision, MRR and nDCG for retrieval; factuality and groundedness for answers, reported separately so neither hides the other.

One script tag, your brand

Theme tokens for colour and type, CSS parts for shape, slots for the launcher and header. It renders in a shadow root, so it inherits nothing from your page and breaks nothing on it.

Actions through MCP, behind your policy

Attach any MCP server. Every tool starts off; a lookup can be allowed, a write needs the visitor's confirmation. Each call is logged with who asked and what ran.

Bring your own

Your model, your database, your site

Provider SDKs live in one module and the vector store behind one interface, so none of these choices leaks into the rest of the deployment.

Models

  • OpenAI
  • Anthropic
  • Google
  • Ollama
  • vLLM
  • LM Studio
  • llama.cpp
  • Any OpenAI-compatible endpoint

Storage

  • Postgres 17 + pgvector
  • Weaviate

Your site

  • One script tag
  • Web component
  • React wrapper
  • Next.js
  • Docusaurus
  • Plain HTML
  • HTTP API + OpenAPI
  • TypeScript SDK

Identity

  • Any OpenID Connect issuer
  • Google sign-in for the dashboard

Self-hosted

Your servers, your data, your stores

  • Postgres 17 is the only service to run. It holds rows, the job queue and, by default, the search index through pgvector.
  • The search index can live in a Weaviate cluster you already run instead. Postgres keeps everything else either way. Vector store
  • Conversations stay in your database, in your region. Visitor IP addresses are never stored.
  • The only outbound call is to the model provider you chose: OpenAI, Anthropic, Google, or none at all with a local model.

Install

git clone https://github.com/deskbellhq/deskbell
cd deskbell
cp .env.example .env
docker compose up

Set BETTER_AUTH_SECRET and a model API key in .env first. Requirements: Docker with Compose. Production checklist

Compared

Built to run where your docs live

A hosted docs bot is a service you subscribe to. Deskbell is software you run: the model, the database and the conversations are yours, and the quality is something you can measure instead of take on trust.

Deskbell compared with Hosted docs bots
CapabilityDeskbellHosted docs bots
Where it runs
Your servers. Docker Compose, Postgres is the only service.
The vendor's cloud.
Where conversations live
Your database, your region. Visitor IPs are never stored.
The vendor's servers; regional hosting is typically an enterprise feature.
Model
OpenAI, Anthropic, Google, or a local model. Two variables to switch.
The vendor's choice.
Citations and refusals
A source on every answer; a refusal, kept with its retrieved context, when the docs don't say.
Varies by product.
Unanswered questions
Clustered by meaning, with a trend and a written recommendation per cluster.
Varies by product.
Actions
Any MCP server's tools, each off, allowed or needs-confirmation; writes wait for the visitor's confirmation.
The vendor's own integrations, or none.
Quality you can measure
An eval harness you run in CI, on your corpus, with your judge.
Not something you can run.
Price
$0 to license. You pay for Postgres and model tokens.
Per answer, or on request.
Source
AGPL-3.0 core, MIT widget and SDKs.
Closed.

Pricing and licensing

Free to self-host

$0 to license, unlimited questions, no per-question or per-seat metering, instead of a hosted docs bot billed per answer. You pay for your own Postgres and your own model tokens, or nothing at all with a local model.

The answering core is AGPL-3.0, the widget and SDKs are MIT, and the operations plane is the only commercial part, which isn’t sold yet.

How Deskbell’s licensing is divided between the open core and the commercial edition
LayerLicense
The answering coreRetrieval, grounding, citations, refusals, connectors, eval harnessAGPL-3.0
Everything that touches your page or codeWidget, web component, React wrapper, typed client, UI kitMIT
The operations planeMulti-organisation management, SSO/SCIM, audit log, white-label rightsCommercial

The boundary is written in the repository’s LICENSE and packages/ee/FEATURES. Pricing and licensing in detail

Roadmap

What works today, and what comes next

Works today

  • Docs-site crawler: sitemap first, robots.txt respected, resumable re-indexing
  • Grounded answers with citations and refusals
  • Embeddable widget: shadow DOM, brandable, inline mode, Markdown answers
  • Dashboard: Sources, Conversations, Gaps, Appearance, Install, Members
  • Sign-in with email and password, invitation-only membership, roles
  • Widget abuse protection: origin allowlist, rate limits, daily token budgets
  • End-user identity through your OpenID issuer
  • Gap analytics, clustered by meaning, with CSV and eval-dataset export
  • Eval harness that runs in CI
  • pgvector by default, Weaviate as an optional vector-store driver
  • Notifications on negative feedback: Slack, signed webhook
  • Actions through MCP: servers per project, each tool off, allowed or needs-confirmation, confirmation card, signed visitor identity, actions log with CSV
  • Conversation retention window per project
  • Public HTTP API with an OpenAPI document, and a typed TypeScript SDK the widget itself runs on

Next

  1. 1Connectors beyond the docs crawlerThe same index, fed from more than a sitemap.
  2. 2Retrieval endpoint and an MCP server for your docsThe chunks that match a question, each with its source page, over HTTP and over MCP, for the agents and UIs you build.
  3. 3Several projects in one workspaceCreate a project and switch between them, each with its own sources, widget key, appearance and policies.
  4. 4Hand-off to a humanWhat the docs cannot answer goes to the helpdesk you already run.
  5. 5Audit log retention and exportEvery action call kept for as long as your auditors need, and exportable.

Full roadmap

Not on the roadmap: a helpdesk. Deskbell overlays the one you have.

Questions

Before you clone it

What does it cost to run?

Nothing to license. You pay for a Postgres instance and for tokens from the model provider you choose, or nothing at all with a local model through Ollama. There is no per-question metering and no seat cap.

Which models can I use?

OpenAI, Anthropic, Google, any local model served through Ollama, and anything that speaks the OpenAI-compatible protocol, such as vLLM, LM Studio or llama.cpp. Switching is a configuration change.

What do I need to run it?

Docker with Compose and an API key for a model provider. Compose starts Postgres; vectors and the job queue live in the same database, so there is no Redis, no Kafka and no separate vector store.

Does it replace my helpdesk?

No. Deskbell overlays whatever you already run. It answers what your documentation covers and, on the roadmap, hands the rest to a human in your existing tool.

Can it take actions, not just answer?

Yes, through MCP. Attach any MCP server to a project and its tools appear in the dashboard, every one off by default. A lookup can be set to allowed; a write is set to needs-confirmation, so the model may propose it but it runs only after the visitor confirms a card. The visitor's identity reaches the server as a signed token and every call lands in an audit log, because a public widget with write access is a prompt-injection target.

Is it GDPR and EU AI Act friendly?

Conversations stay in your database and your region, and visitor IP addresses are never stored. The only outbound call is to the model provider you picked; a local model removes it.

Why not build this myself with a RAG library?

A weekend build gets you retrieval and a chat box. What it skips is the part that makes the answers safe to put in front of users: refusing when the retrieved context does not answer, keeping citations honest, clustering the questions the docs could not answer, and an eval harness that tells you whether a change made answers better or worse. Those are most of Deskbell, and they are the parts that keep needing work.

How does it compare with Kapa.ai?

Kapa is hosted software: you cannot run it yourself and every widget query goes through Kapa's servers. Deskbell runs on your infrastructure with any model and is free to self-host. Kapa is more mature today.

Point it at your docs

Clone it, add a documentation URL, then ask it something the docs answer and something they don’t.

Star on GitHub

Want to contribute? Good first issues