Skip to content

Configuration reference ​

Every setting in one place. Knowledge Index reads two kinds of settings:

  • the project file kb.projects.toml: which projects to index and how they connect;
  • environment variables KB_*: where files live, how the servers behave, what is switched on.

kb --version prints where the project file and the data folder are. A setting that is not set takes the default shown here.

The project file: kb.projects.toml ​

One [[project]] block per project. Only name is required; a project with docs and no code is a docs-only project.

toml
[[project]]
name   = "api"
code   = ["/srv/shop/api/app"]
docs   = "/srv/shop/api/docs"
routes = "/srv/shop/api"

[[project]]
name   = "web"
code   = ["/srv/shop/web/src"]
calls  = ["/srv/shop/web/src"]
serves = "api"
KeyTypeDescription
namestringThe project's name in answers and in access rules. Letters, digits and -.
codelist of pathsFolders whose code goes into the graph. vendor, node_modules, tests, build output and images are left out.
docspathThe docs folder: Markdown is searched; PDF, DOCX, ODT, RTF, EPUB and scans are extracted to text first.
routespathA Laravel app folder: php artisan route:list --json there gives the route table, and its routes become graph edges.
callslist of pathsFolders with frontend or backend code whose HTTP calls are linked to the routes of serves.
servesstring or listThe project(s) whose routes these calls go to, e.g. "api" or ["api", "billing-api"].

Where files live ​

VariableDefaultDescription
KB_HOME—One folder for data and config together, e.g. /srv/kb. Overrides the two below.
KB_DATA~/.local/share/knowledge-index (a checkout: the checkout)Built graphs, staged code and docs, logs, counters, add-on state.
KB_CONFIG~/.config/knowledge-index (a checkout: the checkout)kb.projects.toml, kb.hubs.txt, admins.txt.
KB_COLLECTIONkbPrefix of the docs search collections (kb-<project>).
KB_SELF_DOCS_NAMEkbProject name for a checkout's own docs/ folder.
KB_ALIASESthe shipped tableAlias table for search (term = synonym, synonym).

Building the index ​

VariableDefaultDescription
KB_FORCE01 rebuilds every project and every step, as kb build does. kb update otherwise skips what did not change.
KB_EXTRACT10 skips text extraction from PDF, DOCX and scans.
KB_OCR_LANGSengTesseract languages for scans, e.g. eng+lav+rus.
KB_QMD_BACKENDasked once, then rememberedEmbeddings: llama (on device), none (keywords only) or other (your own command).
KB_QMD_EMBED_CMD—With other: the command that computes embeddings.
KB_REFRESH_WAIT_LOCK—kb-refresh waits while your deploy holds this lock file.

Answers ​

VariableDefaultDescription
KB_DOCS_MODElightDocs search: light (no reranker, ~650 MB RAM), full (LLM reranker, slow on a CPU), bm25 (keywords, ~70 MB).
KB_PAGE_CHARS6000Characters per page of a long answer; a call can ask for 1,000-50,000 with page_length.
KB_CURSOR_TTL600Seconds a long answer stays behind its cursor.
KB_CURSOR_MAX500Answers kept behind cursors at once.
KB_CONTRACT_EDGES10 hides other projects' ends of HTTP edges from a caller limited to some projects.
KB_SESSION_DIRthe current folderThe folder that decides a session's default projects.

Speed ​

VariableDefaultDescription
KB_WARM10 runs graphify and qmd as one process per call instead of keeping them loaded.
KB_GRAPH_CACHE_FILES2Graph files the graph worker keeps parsed.
KB_GRAPH_VIEWS8Caller views (one per project set) kept cut in memory; the recent ones are re-cut after each build.
KB_FAST_ROUTESset by the fast-routes add-on1 computes graph_routes on rustworkx.
KB_MAX_GRAPH_JOBS3Graph calls at once on the shared server.
KB_MAX_DOCS_JOBS1Docs searches at once on the shared server.

Add-ons ​

VariableDefaultDescription
KB_ADDONS<data>/addons.jsonComma-separated add-ons that are on, overriding the file; none switches all off. Names: code-mode, tool-multicall, fast-routes, metrics, admin, audit, and installed plugins.
KB_BATCH_MAX10Calls in one batch.
KB_RUN_SECONDS20CPU seconds a run_code program may use.
KB_RUN_CALLS30Tool calls a run_code program may make.
KB_METRICSoffon serves /metrics without the add-on.
KB_METRICS_TOKEN—Bearer token or basic-auth password for /metrics from outside loopback.
KB_ADMINS<data>/admins.txtComma-separated user names allowed into /admin on the shared server.

The shared server (kb-http) ​

VariableDefaultDescription
KB_SERVERoffMust be on, or the server does not start.
KB_HTTP_HOST127.0.0.1Address to listen on; put a TLS proxy in front.
KB_HTTP_PORT8790Port to listen on.
KB_PERMISSION_URL— (required)The permission webhook: token and project list in, allowed projects out. See access protocol.
KB_LOGIN_URL—The login webhook for browser sign-in, the admin pages and kb-login.
KB_HOOK_HEADERS—Extra headers for both webhooks, a JSON object.
KB_AUTH_CACHE_SECONDS60How long a permission answer is kept, per token hash.
KB_AUTH_TIMEOUT10Timeout of a webhook call, seconds.
KB_AUTH_HINTa sign-in hintText a caller without a valid token gets.
KB_OAUTHonoff turns browser sign-in off: ready tokens only.
KB_OAUTH_TOKEN_TTL28800expires_in told to the client; the login webhook decides the real lifetime.
KB_LOGIN_ENV<data>/kb-login.env, then <data>/deploy/kb-login.envA KEY=VALUE file with KB_LOGIN_URL and KB_HOOK_HEADERS.
KB_USAGE_FILE<data>/logs/usage.jsonBase name of the usage database (usage.sqlite next to it).
KB_SOURCE_URLthe public repositoryWhere users find the source of what they use (AGPL); set it for a changed copy.

Clients ​

VariableDefaultDescription
KB_URL—The shared server's /mcp address for kb-login.
KB_API_TOKEN—Token for the local HTTP API (kb-api --token).

AGPL-3.0-or-later