DocBrain Configuration Reference¶

DocBrain uses a layered configuration system. Settings are resolved in this order (later = higher priority):

{DOCBRAIN_CONFIG_DIR}/default.yaml — committed base defaults
{DOCBRAIN_CONFIG_DIR}/{APP_ENV}.yaml — environment overrides (APP_ENV=development|production)
{DOCBRAIN_CONFIG_DIR}/local.yaml — gitignored developer overrides (optional)
Environment variables — always win; all existing env var names work unchanged

Config File Location¶

Variable	Default	Description
`DOCBRAIN_CONFIG_DIR`	`config`	Directory containing YAML config files. Override for Docker (`/etc/docbrain`), Kubernetes ConfigMap mounts, or custom bare-metal paths.
`APP_ENV`	`development`	Selects `{APP_ENV}.yaml`. Use `production` in production deployments.

The server also accepts --config-dir <path> as a CLI argument (takes precedence over DOCBRAIN_CONFIG_DIR).

Deployment examples:

# Bare metal — default (uses ./config/)
./docbrain-server

# Docker with mounted config dir
docker run -e DOCBRAIN_CONFIG_DIR=/etc/docbrain -v /host/config:/etc/docbrain docbrain-server

# Kubernetes ConfigMap
# Mount ConfigMap at /etc/docbrain and set DOCBRAIN_CONFIG_DIR=/etc/docbrain

# Custom path via CLI arg
./docbrain-server --config-dir /opt/myapp/docbrain-config

Infrastructure¶

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string. e.g. `postgres://user:pass@host:5432/db`
`OPENSEARCH_URL`	Yes	`http://localhost:9200`	OpenSearch endpoint
`REDIS_URL`	No	`redis://localhost:6379`	Redis for working memory (session context). Optional — falls back to in-memory if not set.

LLM Provider¶

Set LLM_PROVIDER to choose your LLM backend. Supported providers: anthropic, openai, bedrock, ollama, groq, openrouter, together, deepseek, mistral, xai, gemini, azure_openai, cohere.

Variable	Provider	Description
`LLM_PROVIDER`	All	Which LLM to use (see list above)
`LLM_MODEL_ID`	All	Model identifier (e.g. `claude-sonnet-4-5-20250929`, `gpt-4o`). Defaults to a provider-appropriate model if not set.
`ANTHROPIC_API_KEY`	anthropic	Your Anthropic API key
`OPENAI_API_KEY`	openai	Your OpenAI API key
`AWS_REGION`	bedrock	AWS region for Bedrock (e.g. `us-east-1`)
`AWS_ACCESS_KEY_ID`	bedrock	AWS access key (optional — see credential chain below)
`AWS_SECRET_ACCESS_KEY`	bedrock	AWS secret key (optional — see credential chain below)

AWS Credential Chain: Bedrock uses the AWS SDK default credential chain: env vars → ~/.aws/credentials → IRSA (EKS) → EC2 Instance Profile → ECS Task Role. In production, use IRSA or instance profiles — no keys in env. Set serviceAccount.create=true and serviceAccount.annotations.eks.amazonaws.com/role-arn in Helm. The IAM role needs bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream permissions. | OLLAMA_BASE_URL | ollama | Ollama server URL (e.g. http://localhost:11434) | | OLLAMA_TIMEOUT_SECS | ollama | HTTP timeout in seconds (default: 120). Increase for large/slow models (e.g. 70B) to avoid "error decoding response body" when the model takes longer than 2 minutes. Example: 300 or 600. | | OLLAMA_TLS_VERIFY | ollama | Set false to skip TLS verification (default: false) | | FAST_MODEL_ID | All | Fast/cheap model for background side-calls: intent classification, query rewriting, entity extraction. Falls back to LLM_MODEL_ID if not set. Recommended: Haiku (Bedrock/Anthropic), gpt-4o-mini (OpenAI), llama-3.1-8b-instant (Groq). Alias: HAIKU_MODEL_ID (deprecated). | | INGEST_LLM_MODEL_ID | All | Model used during ingest only for image extraction. Falls back to LLM_MODEL_ID if not set. Use a cheaper model here — image extraction fires for every page with images and does not benefit from a powerful model. Example: use LLM_MODEL_ID=claude-opus-4 for Q&A and INGEST_LLM_MODEL_ID=us.anthropic.claude-haiku-4-5-20251001-v1:0 for ingest. Not setting this when using Opus 4 + extended thinking will cause throttling errors during ingest. | | DRAFT_MODEL_ID | All | Model used for autopilot draft generation (two-phase reasoning + writing). Falls back to LLM_MODEL_ID if not set. Use a high-capability model here — drafts benefit from stronger reasoning. Example: claude-opus-4 or gpt-4o. | | DRAFT_LLM_PROVIDER | All | Provider for draft generation. Falls back to LLM_PROVIDER if not set. Allows cross-provider drafting — e.g. use Gemini Flash for Q&A but Anthropic Claude for drafts. When set, DocBrain creates a separate LLM client for draft generation. | | LLM_THINKING_BUDGET | anthropic/bedrock | Extended thinking token budget (tokens). 0 or unset = disabled. Only applies to the primary LLM_MODEL_ID — never to FAST_MODEL_ID or INGEST_LLM_MODEL_ID. |

OpenAI-compatible providers¶

The following providers use the OpenAI Chat Completions API format. Set LLM_PROVIDER to the provider name and the corresponding API key:

Provider	`LLM_PROVIDER`	API Key Variable	Default `LLM_MODEL_ID`
OpenAI	`openai`	`OPENAI_API_KEY`	`gpt-4o`
Groq	`groq`	`GROQ_API_KEY`	`llama-3.3-70b-versatile`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	`openai/gpt-4o`
Together AI	`together`	`TOGETHER_API_KEY`	`meta-llama/Llama-3.3-70B-Instruct-Turbo`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek-chat`
Mistral	`mistral`	`MISTRAL_API_KEY`	`mistral-small-latest`
xAI (Grok)	`xai`	`XAI_API_KEY`	`grok-3`
Google Gemini	`gemini`	`GEMINI_API_KEY`	`gemini-2.5-flash`

You can also use OPENAI_BASE_URL with LLM_PROVIDER=openai to point at any OpenAI-compatible proxy (e.g. LiteLLM, vLLM, LocalAI).

Azure OpenAI¶

Variable	Required	Description
`AZURE_OPENAI_API_KEY`	Yes	Azure OpenAI API key
`AZURE_OPENAI_ENDPOINT`	Yes	Resource endpoint. e.g. `https://my-resource.openai.azure.com`
`AZURE_OPENAI_API_VERSION`	No	API version. Default: `2024-02-01`
`LLM_MODEL_ID`	Yes	Deployment name (e.g. `gpt-4o`) — must match your Azure deployment

Example:

LLM_PROVIDER=azure_openai
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
LLM_MODEL_ID=gpt-4o           # your deployment name

Cohere¶

Variable	Required	Description
`COHERE_API_KEY`	Yes	Cohere API key
`LLM_MODEL_ID`	No	Default: `command-r-plus`

Vertex AI¶

Vertex AI lets you run Gemini (and other hosted models) through Google Cloud with enterprise security, VPC controls, and no data leaving your GCP project.

Variable	Required	Description
`VERTEX_PROJECT`	Yes	GCP project ID (e.g. `my-project-123`)
`VERTEX_REGION`	No	GCP region. Default: `us-central1`
`LLM_MODEL_ID`	No	Model ID. Default: `google/gemini-2.5-flash`

Authentication uses the GCP credential chain in order: 1. GOOGLE_APPLICATION_CREDENTIALS env var pointing to a service account JSON file 2. Application Default Credentials (gcloud auth application-default login) 3. GKE Workload Identity (attach a KSA to a GSA with roles/aiplatform.user) 4. GCE metadata server (Compute Engine / Cloud Run default service account)

Example:

LLM_PROVIDER=vertex_ai
VERTEX_PROJECT=my-project-123
VERTEX_REGION=us-central1
LLM_MODEL_ID=google/gemini-2.5-flash
# No API key needed — uses GCP credential chain

For Kubernetes/GKE with Workload Identity:

serviceAccount:
  annotations:
    iam.gke.io/workload-identity-pool: "my-project-123.svc.id.goog"
    iam.gke.io/service-account: "docbrain@my-project-123.iam.gserviceaccount.com"

Note: Vertex AI support requires the vertex feature flag. The Docker image and Helm chart include this feature by default.

Embedding Provider¶

Set EMBED_PROVIDER to choose your embedding model. One of: openai, bedrock, ollama.

Variable	Provider	Description
`EMBED_PROVIDER`	All	Which embedding model to use: `openai`, `bedrock`, `ollama`
`EMBED_MODEL_ID`	All	Embedding model identifier (e.g. `text-embedding-3-small`, `cohere.embed-v4:0`)

Switching Embedding Models¶

When you change EMBED_PROVIDER or EMBED_MODEL_ID to a model with different vector dimensions (e.g. Bedrock Cohere/1024 → Ollama nomic-embed-text/768), the server will refuse to start with a clear error:

Embedding dimension mismatch on index 'docbrain-chunks': existing=1024, required=768.

To migrate:

Set FORCE_REINDEX=true in your environment
Restart the server and run ingest — the old indexes are deleted and recreated
Remove FORCE_REINDEX after the migration completes

Variable	Default	Description
`FORCE_REINDEX`	`false`	Delete and recreate OpenSearch indexes when embedding dimensions change. Set once during migration, then remove.

Document Sources¶

A source is enabled by the presence of its block under the top-level sources: key in config/default.yaml or config/local.yaml — there is no env var that selects a source.

SOURCE_TYPE no longer exists. Earlier versions selected the source with SOURCE_TYPE=local|confluence|github. It is gone from the code; setting it has no effect. If you set it and nothing else, ingest falls back to the LOCAL_DOCS_PATH default (./examples/sample-docs) and DocBrain answers from the sample documents while appearing to work. Enable the sources: block instead — see Ingestion and the quickstart.

Resource lists (spaces, repos, projects, channels) are always explicit; an empty list is a startup error, never "ingest everything the token can see".

sources:
  local:
    path: /path/to/docs        # or set LOCAL_DOCS_PATH
  confluence:
    base_url: https://your-org.atlassian.net/wiki
    user_email: ${CONFLUENCE_USER_EMAIL}
    api_token: ${CONFLUENCE_API_TOKEN}
    space_keys: [DOCS, ENG]

The scalar credentials below are still read from the environment; only the source selection and the resource lists moved to YAML.

Local Files¶

Variable	Default	Description
`LOCAL_DOCS_PATH`	`./examples/sample-docs`	Path to local markdown/text files to ingest

Confluence¶

Variable	Default	Description
`CONFLUENCE_BASE_URL`	—	Full Confluence base URL. e.g. `https://your-org.atlassian.net/wiki`
`CONFLUENCE_USER_EMAIL`	—	Email of the Confluence user (Cloud only — not used for Data Center)
`CONFLUENCE_API_TOKEN`	—	API token (Cloud) or Personal Access Token (Data Center)
`CONFLUENCE_SPACE_KEYS`	—	Comma-separated space keys to ingest. e.g. `DOCS,ENG,PLATFORM`. Optional when `CONFLUENCE_PAGE_IDS` is set.
`CONFLUENCE_PAGE_IDS`	—	Comma-separated page IDs to ingest, including all descendants. Pages can be from different spaces. e.g. `421856743,41912006`. Can be used alone or together with `CONFLUENCE_SPACE_KEYS`.
`CONFLUENCE_API_VERSION`	`v2`	`v2` for Confluence Cloud, `v1` for self-hosted Data Center
`CONFLUENCE_PAGE_LIMIT`	`0`	Max pages to ingest per space. `0` = unlimited
`CONFLUENCE_TLS_VERIFY`	`true`	Set to `false` if using self-signed or internal CA certificates

Ingestion modes:

Mode	Config	Behaviour
Whole spaces	`CONFLUENCE_SPACE_KEYS=DOCS,ENG`	All pages in the listed spaces
Specific page trees	`CONFLUENCE_PAGE_IDS=421856743,41912006`	Listed pages + every descendant, from any space
Both	`CONFLUENCE_SPACE_KEYS=DOCS` + `CONFLUENCE_PAGE_IDS=421856743`	Spaces first, then any page trees not already covered

GitHub PR Reviews (`INGEST_SOURCES=github_pr`)¶

Ingests merged pull request descriptions and review comments as searchable documents. This captures the architectural "why" that lives in code review threads.

Variable	Default	Description
`GITHUB_PR_TOKEN`	—	GitHub personal access token with `repo:read` (or `public_repo`) scope
`GITHUB_PR_REPO`	—	Repository in `owner/repo` format. e.g. `acme/platform`
`GITHUB_PR_LOOKBACK_DAYS`	`365`	How many days back to ingest merged PRs
`GITHUB_PR_MIN_COMMENTS`	`1`	Minimum total review comments required to index a PR. Set higher (e.g. `3`) to skip trivial PRs.
`GITHUB_PR_LABELS`	—	Comma-separated label filter. Only PRs with at least one matching label are indexed. Empty = index all.
`GITHUB_PR_API_URL`	`https://api.github.com`	Override for GitHub Enterprise deployments

Notes: - Only merged PRs are indexed — open, closed-without-merge, and draft PRs are skipped. - Bot comments (Dependabot, GitHub Actions, Codecov, etc.) are automatically filtered out. - Deleted review comments (empty body) are excluded. - Very large PR comment threads (100+ comments per PR) are paginated automatically. - Cross-document references are automatically extracted from PR body and review comments — URLs to Jira tickets, other PRs, GitLab MRs, Confluence pages, and Slack threads are classified and stored in the reference graph. - GitHub API rate limit is 5000 req/hr for authenticated tokens. A full initial sync of a large repo may approach this limit; subsequent syncs only fetch updated PRs.

GitHub Capture Webhook Security (`INGEST_SOURCES=github_pr` + real-time capture)¶

The GitHub capture feature lets engineers trigger ingestion by commenting @docbrain capture on any PR or issue. These optional variables restrict which repos and users can trigger captures.

Variable	Default	Description
`GITHUB_CAPTURE_ALLOWED_REPOS`	—	Comma-separated `owner/repo` pairs that are allowed to trigger capture. Empty = all repos. e.g. `myorg/backend,myorg/frontend`
`GITHUB_CAPTURE_ALLOWED_USERS`	—	Comma-separated GitHub usernames allowed to trigger capture. Empty = all users. e.g. `alice,bob`

A 500KB content size guard is applied to all capture requests. If a PR or issue thread exceeds this limit, DocBrain posts a reply explaining that the thread was too large to capture.

GitLab MR + Review Notes (`INGEST_SOURCES=gitlab_mr`)¶

Ingests merged merge request descriptions and discussion threads. Works with gitlab.com and self-hosted GitLab instances.

Variable	Default	Description
`GITLAB_MR_TOKEN`	—	GitLab personal or project access token with `api` scope
`GITLAB_MR_BASE_URL`	`https://gitlab.com`	Base URL for self-hosted GitLab (e.g. `https://gitlab.mycompany.com`)
`GITLAB_MR_PROJECT_IDS`	—	Comma-separated project paths or IDs. e.g. `acme/platform,acme/backend`
`GITLAB_MR_LOOKBACK_DAYS`	`365`	How many days back to ingest merged MRs
`GITLAB_MR_MIN_NOTES`	`1`	Minimum discussion notes to index an MR. Set higher to skip trivial MRs.
`GITLAB_MR_LABELS`	—	Comma-separated label filter. Empty = index all.
`GITLAB_MR_TLS_VERIFY`	`true`	Set to `false` to skip TLS certificate verification for self-hosted with internal CA

Notes: - Only merged MRs are indexed — open, draft (Draft: / WIP: title prefix or draft: true field), and unmerged MRs are skipped. - System notes (label changes, approvals, "merged" events) are automatically filtered — only human discussion notes are indexed. - Cross-document references are automatically extracted from MR descriptions and notes — URLs to GitHub PRs, Jira tickets, Confluence pages, and other GitLab MRs/issues are classified. GitLab shorthand references (!123 for MRs, #123 for issues) within the same project are also resolved. - Pagination uses the X-Next-Page response header pattern. - GitLab.com rate limit: 600 req/min. Self-hosted limits vary.

GitLab MR Capture Webhook¶

The GitLab capture feature lets engineers trigger ingestion by commenting @docbrain capture on any merge request. When triggered, DocBrain fetches the full MR discussion (excluding system notes) and indexes it immediately.

Setup:

Generate a webhook secret:
```
openssl rand -hex 32
```

Set environment variables:

GITLAB_CAPTURE_WEBHOOK_SECRET=your-webhook-secret
GITLAB_CAPTURE_TOKEN=glpat-...         # Personal access token with api scope
GITLAB_CAPTURE_BASE_URL=https://gitlab.com   # Default; set for self-hosted instances
GITLAB_CAPTURE_ALLOWED_USERS=alice,bob       # Optional — empty = all users
GITLAB_CAPTURE_ALLOWED_PROJECTS=myorg/myrepo # Optional — empty = all projects

Register the webhook in GitLab: Project → Settings → Webhooks
URL: https://your-docbrain-host/api/v1/gitlab/events
Secret token: same value as GITLAB_CAPTURE_WEBHOOK_SECRET
Trigger: enable Comments
Save webhook

Behavior: - DocBrain only responds to comments containing @docbrain capture - All MR notes are fetched (system notes like merge bot events are excluded) - A 500KB content size guard is applied — threads exceeding this limit are skipped silently (no reply) - On success, DocBrain posts a reply note: ✅ Captured by DocBrain — N chunks indexed and immediately searchable.\nThis MR will feed Autopilot's next gap analysis run. - On failure, DocBrain posts: ⚠️ Capture failed: <error> - Reply notes are only posted when GITLAB_CAPTURE_TOKEN is set - User and project allowlists prevent unauthorized users or repos from triggering capture

Variable	Default	Description
`GITLAB_CAPTURE_WEBHOOK_SECRET`	—	HMAC secret shared with GitLab for webhook signature verification
`GITLAB_CAPTURE_TOKEN`	—	GitLab personal access token with `api` scope, used to fetch MR notes and post reply comments
`GITLAB_CAPTURE_BASE_URL`	`https://gitlab.com`	GitLab instance base URL (override for self-hosted)
`GITLAB_CAPTURE_ALLOWED_USERS`	—	Comma-separated GitLab usernames allowed to trigger capture. Empty = all users.
`GITLAB_CAPTURE_ALLOWED_PROJECTS`	—	Comma-separated project paths allowed to trigger capture. Empty = all projects. e.g. `myorg/myrepo`

Linear (`INGEST_SOURCES=linear`)¶

Ingests completed and cancelled Linear issues. Linear uses Markdown natively — no content conversion needed.

Variable	Default	Description
`LINEAR_API_KEY`	—	Linear personal API key — set in `config/local.yaml` or env var
`LINEAR_TEAMS`	—	Comma-separated team keys to index (e.g. `ENG,OPS`). Empty = all teams.
`LINEAR_LOOKBACK_DAYS`	`365`	How many days back to ingest completed/cancelled issues
`LINEAR_STATES`	`Done,Cancelled,Duplicate`	Comma-separated state names to include

Notes: - Only issues in completed-type states are indexed. Open/in-progress issues are skipped. - Comments are included in the document content with author attribution. - Sub-issues are not fetched for v1 — only top-level issues are indexed. - Linear API rate limit: 1500 req/hr for personal API keys.

PagerDuty (`INGEST_SOURCES=pagerduty`)¶

Ingests resolved incidents as postmortem mini-documents, including a chronological timeline of human actions (notifications, escalations, acknowledgements, annotations, resolutions).

Variable	Default	Description
`PAGERDUTY_API_TOKEN`	—	PagerDuty REST v2 API token — set in `config/local.yaml` or env var
`PAGERDUTY_LOOKBACK_DAYS`	`180`	Days back to ingest resolved incidents
`PAGERDUTY_MIN_DURATION`	`5`	Skip incidents shorter than this many minutes (filters noise/blips)
`PAGERDUTY_SERVICES`	—	Comma-separated PagerDuty service IDs to filter. Empty = all services.