Environment variables

Deskbell is configured entirely through environment variables. .env.example in the repository is the annotated original; this page is the same set organised by what each one affects.

Every variable below has a working default except DATABASE_URL and the provider credentials.

Core

Outbound email

Optional. Powers self-serve password reset and invitation emails on the dashboard. Both variables are required together; with them unset, development prints reset links to the server console and production disables the forgot-password flow (the page says so). Any SMTP provider or local catcher works; for Postmark, the Server API token is both username and password: smtp://TOKEN:TOKEN@smtp.postmarkapp.com:587.

Models

Model ids are provider/model. See Models and providers for what each provider supports.

DESKBELL_PLANNER_MODEL and DESKBELL_JUDGE_MODEL exist as separate settings so that changing the model which writes answers cannot quietly change how questions are resolved or how answers are graded. A cheap fast model is the right choice for the planner. For the judge, use a different model from the one under test: grading a model's answers with that same model is self-assessment, and the harness labels it as such in the report when you do.

Ingestion

Chunk size changes what every embedding is computed from. Stored chunks keep the size they were cut at, so after changing it re-sync your sources; to re-embed an existing corpus after changing the embedding model instead, run pnpm exec tsx scripts/reindex-project.ts --project <id> against the deployment's database, or use Reindex on the Sources page.

Retrieval and planning

always expands first questions as well as follow-ups, which improves retrieval at the cost of one extra model call on every question. off searches the message exactly as typed.

With DESKBELL_CLARIFY=on, a question the retrieved pages answer in more than one way — "how do I configure it?" when three pages each configure something different — comes back as one question with the pages as options, instead of an answer for whichever reading the model picked. The options are always titles of pages that were retrieved; the engine drops anything else, and asks at most once per conversation. It costs accuracy on questions that had one obvious reading, so measure it before turning it on for visitors: Clarifying questions says how, and How it works has the mechanics.

The shipped defaults preserve plain vector search. Everything below the floor in that table changes ranking, and the sizing knobs are a latency budget, not a quality dial: turning them up buys latency and tokens first, and quality only if a measurement says so. Hybrid mode exists because exact tokens (error codes, config keys, identifiers) can match literally where embeddings miss them; the per-document cap exists because one long page can otherwise crowd out a short page that answers the question outright. Reranking never runs as a separate service and degrades to fusion order on any failure or timeout. Two drivers exist. llm asks the configured chat model for an ordering: zero extra dependencies, but seconds of latency and tokens on every answer. local runs a real cross-encoder in-process on CPU in the web app, tens of milliseconds per candidate and no tokens. The Docker images and pnpm install include the library it needs (@huggingface/transformers); a production install that prunes development dependencies adds it with pnpm add @huggingface/transformers. On first use the model weights (~25 MB for the default Xenova/ms-marco-MiniLM-L-6-v2) download from the Hugging Face hub into node_modules/@huggingface/transformers/.cache/. In a container that directory lives in the writable layer, so it survives restarts but not a rebuilt image; mount it or pre-seed it for air-gapped deployments. If the library is missing the driver fails loudly per answer and the engine keeps fusion order. Flip any of these against eval numbers; the harness sweeps them with pnpm sweep.

Conversations

Actions

Servers and per-tool policies are set per project under Settings › Actions (Actions). These bound what one turn may do.

Confirmation requests are signed with a key derived from BETTER_AUTH_SECRET; visitor identity tokens are signed with keys the instance generates on first use and publishes at /api/v1/actions/jwks.

Gaps

A gap is a question the content could not answer. Two of the three signals come from the visitor: a refusal they saw, or a thumbs-down they gave. The third comes from the engine: an answer whose best retrieved passage scored under this floor. Those answers read fine and nobody complains, which is why they need a number. The default was chosen by measuring judged answers against their retrieval scores on the shipped embedding model, and it is a conservative floor: on that set it catches the clearest weak answers and flags about one correct answer in ten. A different embedding model moves the scale, so measure again before trusting the default with one. The floor changes only what the dashboard flags, never what visitors get.

Gap questions are grouped by meaning. The worker embeds each new phrasing with the configured embedding model and joins it to the closest existing cluster when the similarity reaches the threshold, otherwise it starts a cluster. Both values are properties of the embedding model, so after changing the model or the threshold use the Re-cluster action on the Gaps page, which rebuilds every cluster in the project from the questions. An exact repeat of an earlier question never needs an embedding call, and if the embedding provider is unavailable the question still lands in a cluster by its text; the hourly catch-up job fills in what was missed.

An analysis asks the chat model what a cluster of questions is missing from the content and what to write, and suggests marking criteria for the eval case. It runs in the worker, counts against the project's daily token budget, and is skipped when nothing about the cluster changed since the last run. Editors trigger it per cluster or for every open cluster without one, twenty per click. The automatic rule is off by default because it spends tokens on its own: set a threshold and clusters that reach that many occurrences in 30 days are analysed once, without a click.

Abuse protection

The defaults are on and sensible. Security explains what each one guards against.

An empty allowlist behaves differently by environment: development answers any origin so the demo works, production refuses. DESKBELL_ALLOW_ANY_ORIGIN is the documented way out, for the case where you embed on many domains you cannot enumerate.

Per-project spending is configured in the dashboard rather than here. Rate limits protect the deployment, so an operator sets them from outside; the daily token budget belongs to a project, so it lives on the Install page next to the number of tokens that project has used today.

Enterprise Edition

Everything not in that manifest is open source, including the whole answering path. See Licensing for the licence map.