Codumentor logo Codumentor

Configuration

Codumentor is configured through YAML, typically named codumentor.yaml. That file is one layer of configuration. It is the instance only when you pass --config or the process uses workspace home (the usual enterprise-edition server). Community / user-home runs keep data under $CODUMENTOR_HOME even when a project YAML is discovered as an overlay.

This file controls repositories to analyze, file patterns, model settings, and tool behavior.

Which configuration guide is this? This is the complete operator reference — every option, including authentication, the API server, logging, and config inheritance. If you just want a single-user instance running quickly, start with the shorter Setup → Configuration. Community "install once, run anywhere" is in Community. To stand up a team/production instance end-to-end, follow the Self-Hosting Walkthrough.

Tip — edit config from a chat. Instead of hand-editing this YAML, admins can use the Configuration Assistant: an admin-only chat (Admin page → Configuration Assistant) that changes the running instance's config in plain language. It grounds itself in this reference and the live schema, validates the change, shows you the exact YAML diff and whether it applies live / needs a restart, and only writes after you approve — with a timestamped backup and one-step rollback. Enable it with the configuration_assistant plugin. Pass target=user for models and keys, target=project for repos and project plugins, or a loaded file's path (an extends: base, for instance) to edit that file.

Two axes: config layers vs instance home

These are independent. Mixing them is allowed; naming them is the product.

Config layers (what the process believes), later wins:

bundled flavor default  →  user overlay  →  project overlay  →  --config

Instance home (where bytes live): workspace (next to the YAML) · user ($CODUMENTOR_HOME) · ephemeral (tempdir).

Community without --config uses user home. A discovered codumentor.yaml is then a project overlay (repos / project plugins only; it cannot redirect model URLs or auth). Enterprise edition with a project YAML uses workspace home: that YAML is the instance. --config is always trusted.

See How a process finds its configuration below for origins and the untrusted-overlay strip.

Environment Variable Substitution

All string values in the configuration file support environment variable substitution using ${VAR_NAME} syntax. This allows you to keep sensitive values (like API keys) or environment-specific paths out of your configuration files.

Example:

models:
  agent: "${AGENT_MODEL}"
  agent_base_url: "${BASE_URL}/v1"
  embedding_api_key: "${GOOGLE_API_KEY}"

vector_db:
  path: "${DATA_DIR}/vector_db"

repos_dir: "${REPOS_DIR}"

Environment variables are substituted when the configuration is loaded. If a variable is not set, the original ${VAR_NAME} string is kept as-is.

Note: Environment variable substitution works for all string values throughout the configuration, including nested dictionaries and list items.

Config inheritance with extends

You can let one config build on another using the extends key. The value can
be a relative path (resolved from the file that declares it) or an absolute
path. Extends are applied depth-first: parents load first, then the child
overrides them.

# child.yaml
extends: base.yaml        # or a list: [base.yaml, extras/feature.yaml]
models:
  agent: "gemini-2.0-pro" # overrides the parent value
vector_db:
  path: "./data/vector_db_variant" # override while inheriting other settings

Cycles are detected and raise an error. Extends works together with the CLI
-c/--config merging: each file is resolved with its own extends chain, then
the resulting configs are merged in the order you pass on the CLI.

How a process finds its configuration

An effective config is always a merge, later wins:

bundled flavor default  →  user overlay  →  project YAML / --config

codumentor status and GET /ui/config report which layers contributed.

A discovered project YAML (found in CWD or via the git-root search, not
passed as --config) is an overlay when the instance home is user
(community / cd into a clone). That overlay cannot override inference
redirects: models.* base URL and API key fields, and the entire auth:
section. A cloned repo can still name repos and the agent model; it cannot
point the process at an attacker's proxy. When the YAML is the instance
(workspace home, enterprise edition), it is trusted. Explicit --config is always
trusted.

OriginWhen
bundledThe packaged flavor default. Always the first layer on a loader-produced config.
user$CODUMENTOR_HOME/config.yaml contributed (skipped if the file is missing).
explicitYou passed -c / --config PATH.
discoveredThe flavor's default filename (codumentor.yaml, or codumentor-<flavor>.yaml) was found in CWD, at the git root, or in the git root's parent.
ephemeralRetained for reload of processes that recorded this origin before the floor flip. New no-YAML loads record the bundled file as bundled; instance home kind=ephemeral is the persistence axis.

Inspect a running (or about-to-run) process:

codumentor status           # banner: instance home, workspace, config, flavor
codumentor status --json

Under the workspace line, both the banner and status list each repository's
resolved on-disk root — the answer to "is this process pointed at the
checkout I meant". It is worth reading, because a relative repos_dir (and a
relative path: in repos:) is anchored to the directory holding the config
file, never to the directory you launched from: launch inside a worktree
whose config says repos_dir: ".." and the roots are the parent's checkouts.
The startup banner stops after five roots and says how many it withheld;
codumentor status prints them all, and status --json carries them as
workspace.repos.

GET /ui/config includes the same facts as instance_home and config_layers.

Migration: omitted keys now inherit the flavor file

Before this floor flip, a workspace YAML was composed with Pydantic defaults
for any key it omitted. Config.include_patterns defaults to [] ("ingest
by known extension"); default_enterprise.yaml ships a language whitelist
instead. A YAML that never set include_patterns used to mean ingest-by-extension
and now inherits the flavor whitelist.

**If you omitted include_patterns in order to ingest every known
extension, set it explicitly:**

include_patterns: []

The same rule applies to every other key the flavor file sets
(session_report, logging.level, exclude_patterns, plugins, …).
Keys the flavor file also omits still use Pydantic defaults. Complete
files such as codumentor-selfdev.yaml are unchanged: they already set
the keys they care about.

Config() constructed in tests (not via load_config) still uses
Pydantic defaults only.

flavor:

flavor: enterprise    # or personal | marketing | minimal | root | investigate

The build-time edition (what the binary contains) is a different axis;
see Editions. The old config key edition: is aliased onto
flavor: with a startup warning — update it when convenient, but a file that
still says edition: keeps booting on the flavor it names.

--flavor / CODUMENTOR_FLAVOR / invoking codumentor-<flavor> select the
bundled default_<flavor>.yaml floor (and the first-run scaffold when no
file exists). An existing file that sets flavor: still wins. An explicit
--flavor that the merge result contradicts is a hard error.

Configuration File Structure

The configuration file uses the following structure:

repos:
  - "https://github.com/user/repo1.git"
  - "path/to/local/repo2"

repos_dir: "repos"

# include_patterns: []  # empty = ingest every known extension; omit = flavor whitelist
# exclude_patterns use sensible defaults (see below)

ingestion:
  max_file_size: 1048576  # 1 MB (default) — skip files larger than this

chunking:
  size: 1000
  overlap: 100

models:
  embedding: "text-embedding-004"
  embedding_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
  agent: "gemini-2.0-flash"
  agent_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"

vector_db:
  backend: "chroma"
  path: "./data/vector_db"

cache:
  embedding_enabled: true
  embedding_db_path: null
  embedding_max_age_days: 365

agent:
  max_iterations: 10
  storage_dir: "./data/agent_storage"

tools:
  tool_result_max_content_length: 30000  # Max chars before tool output is chunked
  shell_output_max_size: 10240
  file_listing_max_size: 10240
  shell_timeout: 900
  search_concurrency: 5

permissions:
  allow: []                    # operator allow rules (a floor; read-only over the API)
  deny: []                     # operator deny rules — highest priority anywhere
  default_mode: acceptEdits    # default | acceptEdits | auto | plan | bypassPermissions
  allow_bypass: true           # false: users cannot choose "Always allow"
  allow_auto: true             # false: users cannot choose Auto
  reason_argument: required    # required | optional | off

api:
  host: "127.0.0.1"
  port: 2638
  reload: false
  enable_web_ui: true        # Serve the protocol-native /ui/* API + SPA
  enable_openai_api: false   # Legacy OpenAI-compatible /v1/* surface (opt-in)
  stream_flush_ms: 250       # Coalesce streamed deltas into one UI event per beat (0 = per-chunk)
  stream_flush_bytes: 4096   # Flush the delta buffer early once it reaches this size

ui:
  welcome_title: "Welcome to Codumentor"
  welcome_description:
    en: "Your own Intelligent Work Environment (IWE). As the orchestrator, set the direction and coordinate the work of the AI agents across your entire software ecosystem — from interconnected services and legacy systems to undocumented codebases. Decide what happens, approve important operations, and keep the process in your hands throughout."
    hu: "A Codumentor a saját Intelligens Munkakörnyezeted (IWE). Orchestrátorként meghatározod az irányt, és összehangolod az AI-ügynökök munkáját a teljes szoftveres ökoszisztémádban — az összekapcsolt szolgáltatásoktól és legacy rendszerektől a dokumentálatlan kódbázisokig. A fontos műveletek jóváhagyása nálad marad, a folyamatot pedig végig kézben tartod."
  disabled_extensions: []

auth:
  provider: "none"  # Options: "none", "gitea"
  gitea:
    base_url: "https://gitea.example.com"
    token_cache_ttl_minutes: 30  # Token cache TTL in minutes

prompt:
  template_dir: "prompts"
  system_prompt_template: "system_prompt.jinja2"
  max_iterations_notification_template: "max_iterations_notification.jinja2"
  custom_instructions: []
  debug_mode: false
  show_tool_calls: true

logging:
  level: "INFO"
  file: "./logs/codumentor.log"
  logger_levels: {}

plugins:
  - module: "codumentor.plugins.filesync"
    class: "FileSyncPlugin"

Configuration Options

repos

List of repositories to analyze. Entries can be either simple strings (Git URLs or local paths) or structured objects that describe alternative SCM providers:

repos:
  # Git support (string form)
  - https://github.com/example/project.git

  # Explicit configuration for alternate SCMs provided by plugins
  - scm: svn
    url: https://svn.example.com/repos/legacy
    name: legacy_svn
    options:
      branch: trunk

  # Pin to a branch/commit
  - url: https://github.com/example/project.git
    branch: release         # or commit: <sha> / pin: <tag>

  # Inline ref pin using URL suffix (common git syntax)
  - https://github.com/example/project.git@release
  - https://github.com/example/project.git#v1.2.3

  # Use an existing local checkout
  - path: /opt/shared/repo
    branch: feature/search  # optional: will checkout this ref before ingestion

  # Pre-synced directories (requires filesync plugin)
  - scm: filesync
    name: shared_docs
    path: "\\\\fileserver\\engineering\\docs"

  # Ingest only part of a repository
  - name: knowledge-repo
    path: /srv/kb
    ingest_paths: knowledge      # or a list: [knowledge, docs]

##### Managing repositories from the UI

Administrators can add, edit and remove repositories from **Admin →
Repositories** (/admin/repos) instead of editing this file by hand. There is no
separate repository store: this YAML file remains authoritative. The page
edits the repos: list in the leaf config file (the last entry of
CODUMENTOR_CONFIG_FILES) and then drives the same hot-reload the
/admin/config button does, so a hand-edit on the host and a UI edit can never
disagree. Requires the admin:config permission.

What it writes, for an entry added through the form:

repos:
  # your existing entries and their comments are left untouched
  - name: service          # the identity: the clone folder, the file-key prefix
                           # and the @-mention token
    url: https://gitea.example.com/team/service.git
    branch: develop        # omitted entirely when you keep "Remote default"
    options:
      platform: gitea      # pre-filled from the host when recognizable

An scm: svn entry, and an scm: filesync one:

repos:
  - name: legacy-erp
    scm: svn
    url: https://svn.example.com/erp/trunk
    options:
      username: builduser
      password: ${SVN_PASSWORD}   # a reference — never the password itself
      revision: "48213"           # omit to follow the latest
  - name: shared-docs
    scm: filesync
    path: "\\\\fileserver\\projects\\docs"   # the source; copied, never modified
    options:
      target_dir: /srv/codumentor/repos/shared-docs
      clear_target: true          # the target is emptied before every copy

Notes on behaviour worth knowing before you rely on it:

##### ingest_paths: ingesting part of a repository

include_patterns / exclude_patterns are global; ingest_paths is per-repo,
and it narrows the walk rather than filtering its result, so excluded files
are never opened, hashed, or embedded. Use it when a repository's contents are
not homogeneous:

Notes:

Plugins can register additional SCM providers (e.g., "svn", "filesystem") to handle these entries during ingestion.

Generic *_overrides

Any top-level key can have a companion <key>_overrides entry. After configs
are merged (and env vars substituted), overrides are applied automatically:

repos_overrides entries can be plain URL strings (same formats accepted by
repos) — they are normalized to dicts before merging.

Examples:

# base.yaml
logging:
  level: INFO
  logger_levels:
    codumentor.tools: WARNING

repos:
  - name: kb
    url: https://example.com/kb.git
    branch: main

# variant.yaml
logging_overrides:
  json_logging: true
  logger_levels:
    codumentor.tools: ERROR
    codumentor.agent: DEBUG

include_patterns_overrides:
  - "**/*.md"

repos_overrides:
  # Match existing repo by name — only override the branch
  - name: kb
    branch: feature-branch
  # Add a new repo using a plain URL string
  - ssh://git@gitea.example.com:2244/org/sandbox.git
  # Add a new repo with full dict syntax
  - scm: svn
    url: "https://svn.example.com/trunk"
    name: legacy-svn

logging keeps level: INFO, enables JSON logging, and merges logger levels.
include_patterns gains the additional patterns while preserving the base ones.
repos gets the kb repo's branch updated to feature-branch, plus two new
repos appended.

##### Nested *_overrides

*_overrides also works deeper than the top level, using the same merge
rules. This is handy for surgically overriding one item in a nested list of
named items — e.g. a single LDAP directory under auth.ldap_directories —
without restating the whole list (a plain dict merge would replace it).

A nested <key>_overrides entry merges into its sibling <key> when present;
when <key> is absent (e.g. a parent config dropped it), the override applies
to an empty base, so list entries are added and dict values are set directly.

Because any key ending in _overrides is treated as a merge directive at
every level, config field names must never end in _overrides.

# base.yaml
auth:
  provider: ldap
  ldap_directories:
    - name: corp
      server_url: ldaps://corp.example.com
      bind_dn: cn=svc,dc=corp
      bind_password: pw
      base_dn: dc=corp
      security_mode: ldaps
    - name: partner
      server_url: ldaps://partner.example.com
      bind_dn: cn=svc,dc=partner
      bind_password: pw
      base_dn: dc=partner

# variant.yaml — flip only the corp directory to STARTTLS
auth:
  ldap_directories_overrides:
    - name: corp
      security_mode: starttls

corp keeps every other field and switches to starttls; partner is
untouched. An override entry whose name is not present is appended as a new
directory.

plugins

Codumentor supports plugins to extend functionality. Plugins are configured as a list of plugin specifications:

plugins:
  - module: "codumentor.plugins.filesync"
    class: "FileSyncPlugin"
  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      executable: "python"
      args: ["-c", "from mssql_mcp_server import main; main()"]

To change one plugin without restating the whole list, use plugins_overrides
on an extends: child. Entries match by module+class (see
Generic *_overrides above), not by name.

Workspace Isolation Plugin

The workspace isolation plugin sandboxes each conversation session using Linux bubblewrap with overlay filesystems. It requires bubblewrap with overlay support (apt install bubblewrap on current distros), an overlayfs-capable kernel, and — on Ubuntu 24.04+ — userns allowed for the bwrap binary under AppArmor; see Plugins in Production → Workspace isolation prerequisites for the install steps.

plugins:
  - module: codumentor.plugins.workspace_isolation
    class: WorkspaceIsolationPlugin
    priority: 5
    args:
      enabled: true
      workspace_ttl: 86400         # 24 hours
      persistent_home: true        # Persistent, shared $HOME (default: true)
      subagent_isolation: shared   # "shared" (default) or "isolated"
      sandbox:
        unshare_net: true         # Block networking inside sandbox (default)

Key options:

OptionTypeDefaultDescription
enabledbooltrueEnable/disable workspace isolation
workspace_ttlint86400Workspace time-to-live in seconds
persistent_homebooltrueBind-mount a persistent HOME (<workspace>/home/) instead of tmpfs. When true, $HOME survives across sandbox invocations and is shared among the main agent, subagents, and external agents. Set to false for legacy ephemeral HOME.
subagent_isolationstr"shared""shared": subagents share the main agent's sandbox (simple, recommended). "isolated": each subagent gets its own sandbox with VCS integration and merge conflict resolution.
sandboxdict{}Sandbox hardening (see plugin README)

repos_dir

Base directory where repositories will be cloned and stored.

What the file tools may reach outside it. read_file and ripgrep accept
an absolute path outside repos_dir — reading a scratch file the agent just
produced with shell (objdump -d prog > /tmp/dis.txt) no longer needs it
moved into the workspace first. There is no setting for this; the answer is
read from boundaries that are already declared elsewhere, and reads outside the
workspace are refused whenever one of them is in force:

In forceReads outside repos_dirWhy
workspace_isolation (overlay mode)refusedthe sandboxed shell cannot see the host either — the file tools must not become a wider door than the shell
An access profile scoped to named repos (repos: [names] or repos: none), or one that withholds the shell tool (qa_readonly)refusedthe operator declared a boundary; for a principal without shell, "it could read it anyway" is false. Note chat_only does hold shell — what refuses its host reads is the repository scope beside it, and the sandbox it is required to run under
Neither (the default single-host install)allowed, after an approval promptshell is unconfined, so refusing the same path to read_file stopped nothing — but shell asks before reading a host file, so the file tools ask through the same permission provider (a Read(<path>) rule, auto-approved wherever shell is). Reads inside the workspace prompt for nothing

Writes are never relaxed. write_file, replace_in_file and the Office
save tools stay confined to the workspace in every configuration, so a run
cannot leave artifacts outside it. Relative paths (../..) are always resolved
inside their repository — only an absolute path can name a host location.

include_patterns and exclude_patterns

File patterns using gitignore-style glob syntax. These control which files are
considered for ingestion. Files must also pass binary detection and the
max_file_size limit (see ingestion below).

include_patterns (flavor default: language whitelist; Pydantic: [])

When empty, all files with known extensions are included automatically.
Codumentor recognizes ~180 file extensions covering source code, config
files, templates, markup, and documentation. Files with unknown extensions
are still included if they pass a binary-detection heuristic (first 8 KB
checked for null bytes and printable-byte ratio).

default_enterprise.yaml ships a language whitelist (*/.py,
*/.md, …) rather than []. Because that file is the merge floor,
a YAML that omits include_patterns inherits the whitelist. Set
include_patterns: [] explicitly if you want ingest-by-extension.
See Migration: omitted keys now inherit the flavor file.

When non-empty, only files matching at least one pattern are included (whitelist
mode).

exclude_patterns (broad defaults)

# Default exclude_patterns:
exclude_patterns:
  - "**/.git/**"
  - "**/.svn/**"
  - "**/.hg/**"
  - "**/node_modules/**"
  - "**/vendor/**"
  - "**/packages/**"
  - "**/.nuget/**"
  - "**/__pycache__/**"
  - "**/venv/**"
  - "**/.venv/**"
  - "**/*.egg-info/**"
  - "**/.tox/**"
  - "**/.mypy_cache/**"
  - "**/.pytest_cache/**"
  - "**/bin/**"
  - "**/obj/**"
  - "**/dist/**"
  - "**/build/**"
  - "**/out/**"
  - "**/target/**"
  - "**/.idea/**"
  - "**/.vscode/**"
  - "**/.vs/**"
  - "**/.env/**"
  - "**/coverage/**"
  - "**/htmlcov/**"
  - "**/*.min.js"
  - "**/*.min.css"

Pattern syntax:

Important: Setting include_patterns or exclude_patterns in your config
replaces the defaults entirely. To append patterns without losing the
defaults, use the _overrides suffix instead:

# REPLACES defaults — you lose all built-in excludes:
exclude_patterns:
  - "**/my_custom_dir/**"

# APPENDS to defaults — built-in excludes are preserved:
exclude_patterns_overrides:
  - "**/my_custom_dir/**"

The same applies to include_patterns_overrides.

ingestion

Controls document ingestion behavior:

chunking

Controls how documents are split into chunks for vector storage:

models

Model configuration for different AI services:

API keys can be specified in the configuration or through environment variables:

Note: API keys support environment variable substitution using ${VAR_NAME} syntax (e.g., embedding_api_key: "${GOOGLE_API_KEY}"). See Environment Variable Substitution above for details.

Thinking/Reasoning Mode:

Truncated-reply retry policy:

When a reply comes back with finish_reason: length and carries no content and no tool call, the whole reply budget was spent on something unusable (usually reasoning). The agent loop re-rolls that call, bounded at two retries per turn, and then surfaces an error naming agent_max_tokens.

How to tell it took effect. A knob can be accepted with a 200 and discarded before the chat template renders — agent_reasoning_passback above is exactly that on vLLM/SGLang — so "we sent the field" is not evidence. Codumentor logs the retry and its outcome as a pair at WARNING on the codumentor.agent logger:

truncated reply: retrying with {'extra_body': {'chat_template_kwargs': {'enable_thinking': False}}} (mode=less_deliberation), not the identical request
truncation retry probe: mode=less_deliberation attempt=1 overrides={...} -> finish_reason=stop reasoning_chars=0 (attempt that truncated: finish_reason=length reasoning_chars=46012)

If the second line reports the same finish_reason=length and a reasoning size of the same order as the attempt that failed, the ingress took the field and ignored it: the policy is inert and agent_truncation_retry_extra_body is where to state the spelling your ingress does read.

HTTP Timeouts:

Model Profiles (per-subagent model selection):

By default, all subagents use the same model as the main agent. Model profiles let you assign different models to different subagent types — for example, a powerful reasoning model for the main agent and a cheaper, faster model for subagents.

A profile is a named bundle of model configuration: model ID, endpoint, API key, and optional parameters. Profiles are defined under models.profiles and referenced by name from subagent_default (applies to all subagents) or subagent_profiles (per-tool assignments).

models:
  agent: "claude-sonnet-4-20250514"
  agent_base_url: "https://api.anthropic.com/v1/"
  agent_api_key: "${ANTHROPIC_KEY}"

  profiles:
    local-fast:
      model: "qwen3-8b"
      base_url: "http://localhost:8000/v1/"
      api_key: "none"
    cloud-cheap:
      model: "gpt-4o-mini"
      base_url: "https://api.openai.com/v1/"
      api_key: "${OPENAI_KEY}"

  # Default profile for all subagents
  subagent_default: "local-fast"

  # Per-tool assignments (take precedence over subagent_default)
  subagent_profiles:
    explore: "local-fast"
    subagent: "cloud-cheap"
    web_retrieve:
      model: "gpt-4o"
      base_url: "https://api.openai.com/v1/"
      api_key: "${OPENAI_KEY}"

Resolution order: subagent_profiles[tool_name] > subagent_default > global agent settings.

Override values can be a profile name (string) or an inline profile definition (dict). When a profile omits api_key, the global agent API key fallback chain is used.

Available profile fields:

ChatGPT/Codex subscription profiles (provider: openai-subscription)

A profile may be backed by a ChatGPT/Codex subscription instead of an API key.
This takes two fields — the second one is easy to miss and its default is
usually not what you want:

models:
  profiles:
    codex:
      model: gpt-5.5
      base_url: https://chatgpt.com/backend-api/codex/responses
      provider: openai-subscription
      codex_credentials_source: oauth   # NOT the default — see below

codex_credentials_source selects the credential store, and the two stores are
entirely separate:

ValueReadsPopulated by
oauththe oauth plugin's per-user token storeeach user connecting their own account in Settings → Extensions (requires the oauth and openai_codex plugins)
import (default)one encrypted operator rowthe host operator running codex login then codumentor codex import, once

Omitting the field leaves it at import. A profile in that state ignores every
subscription connected in Settings and fails each turn with *"No ChatGPT/Codex
subscription credential configured"* — while the Settings page still shows the
account as connected, since that page reflects the OAuth store the profile is
not reading. If you connected the account through Settings, set
codex_credentials_source: oauth.

The choice is static: neither source falls back to the other. See
plugin-dev/catalog/openai_codex.md.

Reasoning capability (reasoning)

Each model exposes reasoning differently (Qwen hybrids a chat-template switch, OpenAI/OpenRouter an effort enum, gpt-oss a system-prompt string). The record declares that once, per profile. agent_reasoning is the same record for the global agent model.

levels is the ladder this model offers — the rungs the picker draws, named in Codumentor's words and taken from the closed set off · minimal · low · medium · high · xhigh · max (max sits strictly above xhigh). It is a product decision, not a read-out of the endpoint's vocabulary: a token the endpoint accepts but you do not want offered simply stays out of levels. Two optional tables carry the rest:

So a request travels closed scale → rung_map → levels → effort_values → wire. See thinking-modes-vocabulary.md and thinking-modes-rung-mapping.md.

reasoning:
  control: chat_template_kwarg   # none | always | chat_template_kwarg | effort_enum |
                                 # budget_tokens | system_prompt | soft_switch
  levels: [off, low, high]       # the ladder this model offers — the picker's segments
  default: high                  # used when a caller asks for no particular rung
  effort_values: {high: xhigh}   # what the endpoint hears for the `high` segment
  rung_map:                      # optional; unset rungs clamp to the nearest offered one
    medium: low                  #   "medium is low on this model"
    xhigh: high
    max: high
  echo: tool_turns               # never | tool_turns | always — reasoning passback policy

Known subagent tool names: subagent, explore, agentic_developer, web_retrieve, web_search, context_summarization.

Connections (models.connections):

A connection is one endpoint and the models it serves — a company OpenAI key exposing several models, an OpenRouter account, a gateway. Where a profile names one model, a connection lists many, and each listed model becomes a profile named <connection>/<model> that subagent_default, subagent_profiles, fallback_profile and a thinking mode's main/roles can name like any other.

models:
  connections:
    company-openai:
      title: Company OpenAI
      base_url: https://api.openai.com/v1/
      api_key: ${OPENAI_API_KEY}
      models: [gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna]
      light_model: gpt-5.6-luna      # omit = the provider catalog's default
      # privacy: org_cloud           # omit = derived from the host
      temperature: 1.0               # any profile field here applies to every model
      model_settings:                # profile fields per model, replacing the above
        gpt-5.6-sol: {context_window: 400000}
    openrouter:
      base_url: https://openrouter.ai/api/v1/
      api_key: ${OPENROUTER_API_KEY}
      models: [deepseek/deepseek-v4.1-flash]

  subagent_profiles:
    explore: company-openai/gpt-5.6-luna
    web_retrieve: openrouter/deepseek/deepseek-v4.1-flash

thinking_modes

Curated thinking modes — one named setting per conversation that decides which model answers, which model each background role uses, and how hard the assistant reasons. A mode is one altitude above models.profiles: it references profiles rather than replacing them. Delivered by the Thinking Modes plugin, which is enabled in the shipped default config.

Omitting the section ships two built-in modes — Fast and Slow, named after the two ways a person works a problem (why) — plus Custom, the user's own per-role mix of the two. They differ in deliberation alone and name no model, and the default is Slow, so nothing about your requests changes until someone picks Fast. The retired ids balanced and deep still resolve to slow, so stored selections and /mode deep keep working.

thinking_modes:
  default: slow                    # mode for a user who has expressed no preference
  modes:
    fast:
      title: Fast
      description: Answers from what it can see and look up.
      icon: bolt
      cost: 1                      # 1-3 relative badge
      main: local-qwen             # a name from models.profiles
      effort: { default: "off" }   # starts at off; the user can still turn it up
    slow:
      title: Slow
      description: Plans before acting, strongest model for code changes.
      cost: 3
      main: cloud-strong
      roles: { context_summarization: local-qwen, explore: local-qwen }
      effort: { default: medium, allowed: [off, minimal, low, medium, high, xhigh] }
                                   # a ceiling — never `max` on the cloud model
      prompt: |
        Before editing, write a short plan and verify it against the code.

effort is the deliberation dial: how long the assistant reasons before each step, not how many steps it takes. Read the rungs as which instruction the model is given rather than as a quantity of intelligence — medium is the model unsteered, not a midpoint between low and high. See the plugin page for the per-rung table.

FieldDefaultDescription
defaultfirst declared modeMode a user with no preference lands on.
modes.<id>.titlerequiredLabel shown in the picker.
modes.<id>.description""One line under the title.
modes.<id>.iconunsetIcon token for the picker.
modes.<id>.cost2Relative cost/speed badge, 1–3.
modes.<id>.mainunsetProfile the main agent uses, and what unlisted roles inherit. Unset leaves model selection to models:.
modes.<id>.roles{}role → profile name, overriding main for that role.
modes.<id>.effort.defaultunsetRung the mode starts at. Unset = the resolved model's own default.
modes.<id>.effort.allowedunsetRungs a user may select. Unset = every rung the model supports. Intersected with the model's reasoning capability, through its rung_map — a segment is offered when any rung that lands on it is allowed.
modes.<id>.promptunsetInstruction block injected as a stable prefix note while this mode is active.

speech

Speech-to-text / text-to-speech service used by the read_aloud message action, the Voice Mode overlay, and Telegram voice replies. It is a sibling of models, not part of it, because the audio provider is usually a different endpoint than the chat-model gateway (e.g. a local vLLM box serves chat but not Whisper/TTS). Uses OpenAI-compatible audio endpoints (/v1/audio/transcriptions, /v1/audio/speech).

speech:
  enabled: true
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"
  tts_model: "tts-1"
  tts_voice: "alloy"
FieldDefaultDescription
enabledfalseMaster switch. The web read_aloud action and Voice Mode overlay light up only when this is true and api_key resolves to a real value.
base_urlhttps://api.openai.com/v1OpenAI-compatible audio endpoint base URL.
api_keynullSupports ${ENV_VAR} and ${secret:<name>}. Use an ${ENV_VAR} for read-aloud, Voice Mode, and the Telegram bot: a per-user ${secret:...} only resolves inside an agent turn, so it cannot drive those out-of-turn web calls.
stt_modelwhisper-1Speech-to-text model.
stt_languagenullnull = let the provider auto-detect the spoken language.
stt_max_audio_bytes26214400 (25 MB)Reject larger uploads before hitting the provider.
tts_modeltts-1Text-to-speech model.
tts_voicealloyTTS voice.
tts_formatopusopus → Ogg/Opus (native Telegram voice note). Also: mp3, aac, flac, wav, pcm.
tts_speed1.0Playback speed multiplier.
tts_max_input_chars4096Guard against synthesising an enormous reply. 0 disables it.
read_timeout120.0HTTP read timeout (seconds).
max_retries2Retry count for transient provider errors.

See Plugins in Production → Speech for the operational checklist.

vector_db

Vector database configuration:

cache

Embedding caching configuration:

agent

Agent behavior configuration:

tools

Tool-specific configuration:

permissions

The tool-approval gate's operator floor. Everything here is read-only over the API: no user setting, conversation mode or Auto verdict can widen it. See Permissions for the user-facing behaviour.

What reaches the gate. The full list, because two of these are easy to miss:

The last four do not pass through the agent's tool gate, so they carry no model-written reason — see reason_argument below.

File edits inside the workspace do not reach the gate: no file-editing tool requests a permission, so in a conversation no mode and no Write(…) rule stops one. Print mode is the exception, and it is a different mechanism — codumentor -p refuses the file-editing tools by name under default and plan (see default_mode below). The file_write permission type is reserved for the path-aware gating that has not shipped yet — until it does, what confines a write in a conversation is the workspace boundary (see repos_dir), not this block.

Hot-reload class: APPLY — the gate re-reads this block on every tool call, so an edit takes effect on the next one. reason_argument is the exception: it is baked into an agent's tool schema, so cached agents are flushed on reload.

permissions:
  allow: []                    # operator allow rules, same syntax as UI rules
  deny: []                     # operator deny rules — highest priority anywhere
  default_mode: acceptEdits    # what a conversation starts in
  allow_bypass: true           # false: "Always allow" unavailable to users
  allow_auto: true             # false: Auto unavailable to users
  reason_argument: required    # required | optional | off

  auto:                        # Auto mode's triage
    judge_role: permission_judge
    judge_timeout_s: 12
    include_reason: false
    judge_arm_comparison_rate: 0   # 0-1: run both include_reason arms and log the pair
    max_auto_allows_per_turn: 100
    max_judge_calls_per_turn: 100
    revert_to_ask_after:
      consecutive_user_denials: 3
      total_asks: 20
    always_ask_types: [gmail.send, gitea.submit_review, write_system_config]
    user_turns_window: 12
    trajectory_window: 8

  structural:                  # the deterministic command analyser
    readonly_allow: []         # empty = the built-in read-only command set
    max_complexity: 6
    extra_escalate_patterns: []
    project_code_allow_when_isolated: true
FieldTypeDefaultDescription
allowlist[]Operator allow rules (Shell(git status), Read(*.json)). Matched per simple command: every part of a compound command must match, and a command carrying an escalating flag can never be covered.
denylist[]Operator deny rules. The highest priority in the system — no user rule, mode or Auto verdict lifts one. A deny matching any part of a compound command denies the whole thing.
default_modestracceptEditsWhat a conversation starts in when the user has no default of their own. One of default, acceptEdits, auto, plan (read-only), bypassPermissions. default and acceptEdits behave identically in a conversation — in-workspace file edits are ungated either way; they differ only in print mode (-p), where default also refuses the file-editing tools unless --allowed-tools names them.
allow_bypassbooltruefalse removes "Always allow" from every user's choices, including a default they set earlier.
allow_autobooltruefalse removes Auto the same way.
reason_argumentstrrequiredWhether permission-gated tools carry the approver-facing reason argument. optional keeps the field but drops it from required (for providers with strict schema validation); off injects nothing. Costs roughly 35 schema tokens per gated tool and 25 output tokens per gated call.

##### permissions.reason_argument and what carries a reason

The reason is an argument on a tool schema, so it exists only for approvals that come from a tool call the model made: shell commands and every gated plugin tool. The four approvals raised elsewhere carry none, and both dialogs simply omit the line — an out-of-workspace file read (raised inside a read, by the file tool), sandbox_network (asked before the turn's first command runs), an MCP app's tool call, and a nested external agent's call back into Codumentor. A missing reason there is not a model that declined to explain itself.

permissions.auto

Only consulted in Auto mode (whether a user chose it, default_mode set it, or scheduler.permission_mode did).

FieldTypeDefaultDescription
judge_rolestrpermission_judgeThe model_role the tier-2 judge resolves through — map it in models.subagent_profiles to put the judge on a cheaper model. Must not collide with an agent role. Defaults to the agent model with thinking disabled.
judge_timeout_sfloat12.0A judge that has not answered by then prompts instead.
include_reasonboolfalseFeed the agent's reason to the judge as a labelled, grounding-checked claim. Off by default: the evaluation in scripts/eval_permission_triage.py found the channel changed no verdict on 88 of 89 hostile items and, on the 89th, let a rationalising reason turn an ask into an allow. Turning it on gives the judge more to read at the cost of a persuasion channel; the switch exists so the trade-off can be re-measured as the corpus grows.
judge_arm_comparison_ratefloat0.0Fraction of judged calls (0-1) that ask the judge both ways — with the reason and without — in parallel, and answer with the safer of the two: the configured arm's verdict, downgraded to a prompt if the other arm wanted one. It can only ever turn a silent approval into a prompt, never the reverse. Each sampled call costs two judge calls instead of one and writes one line to the log (PERMISSION_JUDGE_ARMS {json}: both verdicts, both notes, agree, and the command and reason clipped to 240 characters). This exists because the setting above is decided one way per install, so no ordinary approval record can say what the other setting would have done; turn it up on a staging instance, or low (0.05) on a busy one, when you want that answer for your own traffic. Calls with no reason are not sampled, and a comparison is skipped when the turn's judge budget has room for only one call.
max_auto_allows_per_turnint100Silent approvals per turn; the next gated call prompts.
max_judge_calls_per_turnint100Judge calls per turn; beyond it, prompt.
revert_to_ask_after.consecutive_user_denialsint3Denying this many Auto-produced prompts in a row switches the conversation back to Ask. A user allow resets the counter.
revert_to_ask_after.total_asksint20Auto asking this many times in one conversation switches it back to Ask.
always_ask_typeslist[gmail.send, gitea.submit_review, write_system_config]Permission types that always prompt, without consulting a judge — the irreversible and outward-facing ones.
user_turns_windowint12How many of the user's own messages the judge sees (first turn plus the last N).
trajectory_windowint8How many recent gated calls appear in the judge's trajectory digest.

The judge never sees tool results, file contents, web pages, the agent's prose or thinking, conversation summaries, or repository instruction files. It cannot approve without quoting words the user actually typed, and any error, timeout or malformed answer prompts.

permissions.structural

The deterministic analyser feeds rule matching, the approval dialogs' badges and Auto's first tier, so a change here is visible in every mode. All three see the operator's knobs below — the gate re-derives a request's analysis from this block before it decides, so these apply with or without workspace_isolation loaded.

Two environments, one analyser. The analyser is given the conversation's sandbox facts where they are reachable, and one flag changes severity with them: network_egress is escalating when the network is reachable and informational when the sandbox has no network of its own. The rule engine cannot see the execution strategy — it is handed a request, not a conversation — so rule matching always analyses in the default environment: unsandboxed, networked, workspace boundary unknown. The consequence operators hit: Shell(git:*) never covers git push, in any sandbox configuration, while the badge on the dialog for that same command may still render in the quiet colour. That asymmetry is the conservative direction and is deliberate; both halves are documented in the user guide.

FieldTypeDefaultDescription
readonly_allowlist[]Overrides the built-in read-only command set. Empty means "use the built-in set" — an empty list is far more likely to be an accident than an intent, so use max_complexity or an escalate pattern to tighten instead. Adding a command here vouches for its whole option surface. The built-in set is narrowed per tool for the options that write a file, run a program or read something the command line never named (sort -o, rg --pre, fd -x, awk's program text, git remote add, …); a name you add gets no such narrowing, so any invocation of it counts as a read. Prefer a tool that cannot write or exec at all.
max_complexityint6Above this many commands + pipes + redirects + heredocs, the command is flagged long_command.
extra_escalate_patternslist[]Regexes matched against the raw command string. A hit escalates, which means no allow rule can cover the command and Auto can never approve it silently. An invalid regex is rejected at config load, not at gate time.
project_code_allow_when_isolatedbooltrueWhether Auto's first tier may approve a command that runs project code (pytest, make, npm test) when the workspace is an isolated sandbox with no shared network. This is an Auto policy, not an analyser input: the analyser always reports the fact.
 
# Single-user developer install: quiet, still audited.
permissions:
  default_mode: auto
# Multi-user team server: users may not switch the gate off, and the
# operator's deny rules are the floor.
permissions:
  allow_bypass: false
  deny:
    - "Shell(sudo:*)"
    # Read(...) covers reads outside the workspace only — a .env inside a
    # repository is read without asking.
    - "Read(.env)"
    - "Read(.env.*)"
# Read-only demo instance.
permissions:
  default_mode: plan
  allow_bypass: false
  allow_auto: false

api

API server configuration:

##### Restarting the server from the Admin page

Administrators with admin:* (the same permission as Config Reload) can
restart a running API process from the web UI — no shell and no change to
systemd or Docker. See Process supervisor
for how the built-in supervisor brings the process back.

On the Admin hub (/admin), the Server section shows version,
edition, how long the process has been up, and whether restart is available.
Restart server… opens a confirmation dialog. The lead line is that
everyone using the server is disconnected for a few seconds. The dialog lists
active work and what happens to it: agent turns resume after the new
boot (when resume_interrupted_turns is on); **in-flight ingestion and
scheduled / triggered runs are aborted and marked failed**, not resumed;
approval waits survive. There is no drain mode — Restart now shuts down
immediately.

If restart is unavailable (for example the server was started with
--no-supervisor, or the home is ephemeral), the button is disabled and the
panel explains why.

On Admin → Config Reload (/admin/config), a "restart required" banner
after a hot-reload that could not apply every change includes Restart now,
which opens the same dialog.

After a restart is accepted, every connected client shows a non-dismissable
Codumentor is restarting… overlay and polls /health until a new boot id
appears, then reconnects.

api.mcp_apps

Interactive MCP Apps are enabled
by default only after the deployment supplies a valid sandbox origin. With
no sandbox_origin, or with an unsafe one, Codumentor stays text-only and does
not advertise the Apps extension to MCP servers.

api:
  external_url: "https://codumentor.example.com"
  mcp_apps:
    sandbox_origin: "https://mcp-app-sandbox.example.net"

The sandbox hostname can reverse-proxy to the Codumentor process. The process
serves only /mcp-app-sandbox.html on that virtual host and returns 404 for API
and SPA routes. Do not attach a broad Domain= cookie to a parent domain shared
by the host and sandbox. If content_security_policy is custom, its
frame-src must explicitly include the normalized sandbox origin.

Roll out by configuring the origin on one instance, confirming the log does not
report an MCP Apps availability reason, and watching
GET /ui/admin/mcp-apps-metrics. Useful signals are lifecycle failed versus
initialized, resource failures/cache hits, RPC outcomes and p95 latency, and
security rejections. The endpoint requires admin:*; POST the corresponding
/ui/admin/mcp-apps-metrics/reset endpoint before a compatibility exercise.
If failures rise, set api.mcp_apps.enabled: false; textual tool results remain
available and existing conversation data needs no migration.

api.app_preview

Runs an agent-built static web app in a sandboxed iframe, so *"build me a small
web app"* ends with something the user can click rather than a file listing.
Same shape and same reasoning as api.mcp_apps above — one more DNS name
pointing at the same process — and deliberately so: an operator should have to
learn this mechanism once.

api:
  external_url: "https://codumentor.example.com"
  app_preview:
    sandbox_origin: "https://preview.example.net"

Without a valid sandbox_origin the feature does not disappear; it runs in
the degraded tier, served from the main origin inside an allow-scripts-only
frame. Relative assets load, so a multi-file build renders; localStorage and
the app's own same-origin fetch() do not, because an opaque origin has no
storage and is same-origin with nothing. (history.pushState() to a same-URL
path does work there — measured, contrary to what the design doc predicted.)
The overlay says so in one line.
Root-absolute asset paths (<script src="/assets/index.js">, the Vite default)
also only resolve on the app tier; build with a relative base
(Vite's base: './') or set sandbox_origin.

The sandbox hostname can reverse-proxy to the Codumentor process. On that
virtual host the process serves only /_app-preview/* and returns 404 for API
and SPA routes — and, symmetrically, /_app-preview/* returns 404 on the
primary host once a valid sandbox origin exists, so the second origin is not
merely optional decoration. As with MCP Apps: do not attach a broad Domain=
cookie to a parent domain shared by the host and sandbox, and if
content_security_policy is custom its frame-src must explicitly include the
normalized preview origin or the feature drops to degraded.

A preview is read-only, confined to one directory subtree, re-authorized
against the minting user's access profile on every request, and served with
connect-src 'self' — the previewed app can fetch its own files and nothing
else. The same policy blocks every off-origin subresource, so an app built
against a CDN will not load its script, stylesheet or font: that is the point
(it is what stops repo bytes leaving through the app), and the overlay's console
badge names the refused requests rather than showing a blank page.

One exposure is worth knowing, because no Content-Security-Policy closes it:
a document can always navigate itself away, so a previewed app could put
data in a URL and go there. In the overlay the page framing it refuses that
navigation — which is why a custom content_security_policy whose frame-src
is broad (*, a bare https:, or a wildcard host) drops this feature to
degraded rather than being accepted. The overlay's Open in new tab opens
the preview with no framing parent and therefore without that refusal; it is
labelled accordingly, and a deployment that does not want it can turn the
feature off or run without a sandbox_origin (the degraded tier hides the
button). See doc/core-dev/design/spa-preview.md §7 for the threat model.

api.rate_limit

Budgets are per client IP per minute; 0 drops a rule. Only the paths listed
are limited — there is deliberately no blanket cap, which would throttle the
SSE stream and the UI's own polling. A refused request gets 429 with
Retry-After.

Two caveats worth knowing. A shared egress IP (corporate NAT) shares a budget —
raise the share limits first if that bites, not the login limit, since the
failure backoff is what actually stops guessing. And the counters are
in-process: a multi-worker deployment divides every budget by the worker count.

ui

Web UI customization:

When welcome_title or welcome_description are not set, the built-in translated defaults are used.

Plain string (same text for every language):

ui:
  welcome_title: "Welcome to ACME CodeBot"
  welcome_description: "Ask questions about our internal services and libraries."

Per-locale map (i18n):

ui:
  welcome_title:
    en: "Welcome to ACME CodeBot"
    hu: "Üdvözöl az ACME CodeBot"
  welcome_description:
    en: "Ask questions about our internal services and libraries."
    hu: "Kérdezz a belső szolgáltatásainkról és könyvtárainkról."

You can mix the two styles — for example a plain welcome_title with a locale-mapped welcome_description.

auth

Authentication configuration for API access:

A browser login sets two cookies, both HttpOnly, and both covered by the
settings above: codumentor_session (the access token) and
codumentor_refresh (the refresh token, SameSite=strict and scoped to
Path=/auth/refresh). Neither token is ever returned in a response body to
the browser, so no script — including an injected one — can read or exfiltrate
a session. Programmatic clients are unaffected: they still get tokens in the
body of POST /auth/login and send them back as
Authorization: Bearer <jwt>.

The configured provider is the only one that can serve an interactive
login: POST /auth/login refuses a caller-supplied provider, and
GET /auth/providers lists only that provider. A provider named in config
whose configuration block is missing is a startup error rather than a silent
fallback to unauthenticated access.

Sessions are revocable. Logging out invalidates both tokens server-side,
refreshing invalidates the token it consumed, and deactivating a user (or
taking a role away) invalidates everything they hold — so those are real events
rather than client-side gestures, and a copied token stops working. Revocations
live in data/auth/revoked_tokens.db so a restart cannot resurrect a
logged-out session; entries are purged automatically once the token they name
has expired anyway. No configuration; see
doc/security/session-credentials.md §6.

See the Authentication guide for the full per-provider reference.

Gitea Provider

Local Provider

A fixed set of username/password users defined in config. The simplest way to give a small team real logins without Gitea or LDAP:

auth:
  provider: local
  jwt_secret: "${CODUMENTOR_JWT_SECRET}"   # keep persistent sessions across restarts
  local:
    users:
      - username: admin
        password: "${CODUMENTOR_ADMIN_PASSWORD}"   # plaintext or pbkdf2_sha256$ hash
        email: admin@example.com
        roles: ["admin", "user", "power_user"]
      - username: dev
        password: "${CODUMENTOR_DEV_PASSWORD}"
        roles: ["user"]

Each entry takes username (required, unique), password (required — plaintext or a pbkdf2_sha256$... hash, ${ENV_VAR} substitution supported), and optional email, display_name, and roles (default ["user"]). Generate a hash with python -c "from codumentor.auth.providers.local import hash_password; print(hash_password('s3cret'))". See Authentication → Local for details.

LDAP Provider

For enterprise environments using LDAP or Active Directory:

auth:
  provider: ldap
  ldap:
    # Connection settings (required)
    server_url: "ldaps://ldap.example.com"  # or ldap:// for non-SSL
    bind_dn: "cn=service,dc=example,dc=com"
    bind_password: "${LDAP_BIND_PASSWORD}"
    base_dn: "dc=example,dc=com"

    # Server type: "active_directory", "openldap", or "generic"
    server_type: "openldap"

    # Security: "ldaps" (SSL), "starttls", or "none"
    security_mode: "ldaps"

    # User search settings
    user_search_filter: "(&(objectClass=inetOrgPerson)(uid={username}))"
    user_search_base: "ou=users,dc=example,dc=com"  # defaults to base_dn
    username_attribute: "uid"  # "sAMAccountName" for AD
    email_attribute: "mail"
    display_name_attribute: "displayName"

    # Group settings (for role mapping)
    group_search_base: "ou=groups,dc=example,dc=com"
    group_member_attribute: "memberOf"

    # Role mapping: LDAP groups → Codumentor roles
    group_role_mapping:
      "cn=admins,ou=groups,dc=example,dc=com": ["admin"]
      "cn=developers,ou=groups,dc=example,dc=com": ["developer"]
    default_roles: ["user"]

    # Optional: require membership in a specific group
    require_group: "cn=codumentor-users,ou=groups,dc=example,dc=com"

    # SSL certificate validation
    validate_cert: true
    ca_cert_file: "/path/to/ca-cert.pem"  # optional

Active Directory defaults (when server_type: active_directory):

OpenLDAP defaults (when server_type: openldap):

Multiple LDAP directories. Replace the ldap: block with a list under
ldap_directories: to authenticate against several independent directories.
Each entry takes the full set of LDAP options shown above plus a unique
name. On login the directories are tried in declared order; the first
successful bind wins. See Authentication
for the routing rules, identity behaviour, and audit-log labelling.

auth:
  provider: ldap
  ldap_directories:
    - name: corp
      server_url: "ldaps://corp.example.com"
      # ... full LDAP options ...
    - name: contractors
      server_url: "ldaps://contractors.example.com"
      # ... full LDAP options ...

prompt

Prompt/template system configuration (see Prompt System for the full reference):

tools

Tool-specific configuration:

When disable_vector_search is set to true, the agent will not use the vector database for semantic search, relying instead on other methods like file reading and shell commands to find information.

task engine

Controls the task engine — the component that fires recurring and one-off jobs onto the job queue (scheduled agent runs, periodic reports, ingestion refresh, etc.).

The task engine shares its SQLite file with the job queue (jobs.sqlite3 by default, overridable via CODUMENTOR_JOBS_DB_PATH). WAL is enabled automatically.

tasks:
  enabled: true
  idle_poll_interval: 30.0       # max seconds between loop ticks when idle
  disable_after_failures: 5      # consecutive infra failures before auto-disable
  max_catchup_age: 86400.0       # 24h — skip fires older than this
  max_tasks_per_user: 1000
  default_timezone: "UTC"
  max_chain_depth: 3             # event triggers: how deep a causal chain may go
  max_fires_per_minute: 60       # event triggers: instance-wide circuit breaker
  event_retention_days: 30       # event triggers: how long the event ledger keeps a row
  allow_agent_created: true      # may an agent create tasks from a conversation?
  # default_run_token_budget: 200000          # per-run token cap; unset = unlimited
  # default_webhook_run_token_budget: 100000  # same, for webhook-fired runs
  # max_run_token_budget: 2000000             # ceiling on any per-run budget
  permission_mode: bypassPermissions   # what an unattended turn may do
FieldTypeDefaultDescription
enabledbooltrueMaster switch. When false, the task engine loop never starts and schedule_* operations will fail. Existing tasks remain in the DB.
idle_poll_intervalfloat30.0Maximum seconds the loop sleeps between ticks when no fires are imminent. Lowering this costs a bit more DB I/O; raising it delays reaction to newly-created tasks up to this bound.
disable_after_failuresint5After this many consecutive infrastructure failures (e.g. database is locked on enqueue), the task is auto-disabled and its status becomes disabled. Handler exceptions do not count — they mark the fired job failed, not the task.
max_catchup_agefloat86400.0If the task engine has been offline and a scheduled fire is older than this many seconds, skip it silently and jump to the next occurrence. Prevents firing a week-long backlog of stale runs after an outage.
max_tasks_per_userint1000Cap on active+paused tasks per owner_user_id. Protects against unbounded growth if users can create tasks interactively.
default_timezonestr"UTC"Default IANA timezone for tasks that don't specify one.
max_chain_depthint3Event triggers. How many hops a causal chain of events may fire before the router refuses. An event arriving from outside (a webhook, an ingestion) is depth 0, and events a run emits are depth+1, so this bounds any cycle at this many fires whatever its shape — A fires B fires A included. A refused fire records a skipped run row with reason chain_depth and logs a WARNING carrying the chain_id, so the whole chain is one list_events(chain_id=...) query. A task may narrow this for itself; it cannot widen it.
max_fires_per_minuteint60Event triggers. Instance-wide circuit breaker across all tasks. Tripping it is logged at ERROR, not WARNING: at this rate something is wrong, not busy. Coalesced events do not each count — a burst that merges into one pending run is charged once. 0 (or negative) disables the breaker; to stop event tasks firing at all, pause them or set enabled: false.
event_retention_daysint30Event triggers. How long the event ledger keeps an event row, purged by the task_tools maintenance sweep (the same daily loop that ages out run history). The capped, debug-only raw webhook body is nulled far sooner — 48h — because it is the bulky part and stops being interesting first. 0 keeps events forever.
allow_agent_createdbooltrueWhether the agent-callable create_task tool may create tasks. Set false to make automation an operator-only act: the tool stays visible and refuses with a reason (so the model is told no rather than inventing a workaround), the task engine keeps running, and user- or config-created tasks are untouched. Independent of the trust boundary — an agent may never create a task firing on a webhook-sourced event type (repo., scm., webhook.*) whatever this says, because an outside party would then influence both whether an unattended turn runs and what text is in its prompt. See triggers §12.1.
default_run_token_budgetintunsetToken budget a scheduled/event run gets when its task (or goal worker) sets none. Counts every token sent to or received from the model, including cached prompt tokens. A run that spends it stops at the next step boundary and is recorded failed with error_kind: token_budget (counts toward a goal worker's auto-disable like a timeout). Unset = unlimited. Minimum 1000.
default_webhook_run_token_budgetintunsetSame, for runs fired by a webhook-sourced event (repo., scm., webhook.*); takes precedence over default_run_token_budget for those runs. Precedence for one run: the task's own token_budget > this (webhook-fired runs) > default_run_token_budget > unlimited.
max_run_token_budgetintunsetCeiling applied to whichever budget wins above, agent- and user-set ones included (like the 6h ceiling on timeout_seconds). Unset = no ceiling; it never turns an unlimited run into a limited one. Minimum 1000, like the other two.
permission_modestr"bypassPermissions"The approvals mode an unattended turn runs in — a scheduled run or a Gitea webhook turn. See below.

Unattended approvals. A scheduled or webhook turn has nobody to answer a
permission prompt, so it does not use the conversation's or the user's mode; it
uses this one. The default, bypassPermissions, is the behaviour Codumentor has
always had: allow everything the operator's deny rules do not refuse.

auto runs the same triage an interactive Auto conversation gets — the
deterministic analyser, then the judge — and because there is nobody to ask,
a call that would have prompted is denied instead. The refusal names the
command, the analyser's flags, the judge's note and the agent's own reason, and
goes three places: the tool result the model reads (so the run's final message
can say what it could not do), the transcript card, and the durable audit row
(decided_by = unattended). The model is told, keeps going, and the run ends
with a report rather than a hang. plan makes unattended turns read-only.
default and acceptEdits degrade the same way as auto but without the
triage, which makes them strict-deny modes rather than useful ones.

Per-run token budgets. A budget bounds one unattended run's spend the way
timeout_seconds bounds its wall time. It is set per task (create_task /
update_task token_budget), per goal worker (token_budget in its
definition.yaml, update_worker, the worker edit form), per declared task
(run.token_budget), or falls back to the defaults above. The effective value
is resolved once when the run starts and stored on the run row, so run history
shows the limit each run actually had. What is counted and when it stops:

Every run (budgeted or not) records input, cached, cache-write, output and
total tokens on its run row; the run card and the goals run panel show them,
with the budget and % used. Cost reads unknown for a model without a price
(never $0); a total mixing priced and unpriced models is a lower bound.
Design: run-token-budgets.

Event triggers. The three max_chain_depth / max_fires_per_minute / event_retention_days fields govern event-driven tasks (on: repo.ingested, on: task.run_finished, …) rather than clock-driven ones; they are inert on an instance with no event tasks. Per-task caps (debounce_seconds, max_delay_seconds, max_fires_per_hour, allow_self) live on the task itself. See triggers §11.

tasks.declared — operator-declared event tasks

A list of tasks the config file owns. They are reconciled against the running
task engine at startup and on every tasks: reload: entries are created,
updated and cancelled to match the list, and nothing a user or an agent created
is touched.

This is also the only surface allowed to declare a task that fires on a
webhook-sourced event type (repo., scm., webhook.*). Such a task lets an
outside party decide both whether an unattended, tool-auto-approving turn runs
and what text is in its prompt, which is an operator decision rather than a
conversational one — so it is refused to an agent whatever allow_agent_created
says, and it is refused here without an access_profile. See
triggers §12.1 and §12.4.

Quote the on: key. PyYAML implements YAML 1.1, whose booleans are
y|yes|n|no|true|false|on|off, so a bare on: parses as the boolean True
and the entry never sees the field it is named after. Write "on":. The
entry is refused with a message spelling out the fix rather than quietly
repaired — accepting the boolean key would make on: work here and nowhere
else you might expect symmetry.

tasks:
  declared:
    - name: review-on-pr
      "on": scm.pull_request        # note the quotes
      scope: my-repo                # optional: the event's scope_key
      when:
        - [action, in, [opened, synchronize]]
      mode: per_event
      on_overlap: queue
      access_profile: pr-reviewer
      run_as: review-bot            # optional: a real account to run as
      description: Review a pull request when it opens or gets new commits.
      run:
        prompt: |
          Review pull request #${event.pr.number} in ${event.repo}.
          Title: ${event.pr.title}
        timeout_seconds: 1800
FieldRequiredDescription
nameyesThe reconciliation key. See the semantics below. Also shown on the run card.
"on"yesThe event type to fire on. A typo is refused at load: for plugin.* types the plugin's declared emits vocabulary is checked too. Use the list_event_types tool to see the vocabulary and what each event carries.
run.promptyesThe turn's instruction text. May carry ${event.<path>} placeholders.
run.timeout_secondsnoWall-clock cap on the fired job. Omitted leaves the queue's own per-queue default in force.
run.token_budgetnoToken cap on the fired run (see default_run_token_budget). Omitted falls back to default_webhook_run_token_budget / default_run_token_budget; clamped to max_run_token_budget.
access_profileconditionalRequired for a webhook-sourced on:; a config error without one. Never event-chosen.
run_asnoThe run identity: it becomes job_args["user_id"], which is the account the turn executes as and what per-user secrets are keyed on — so a declared task that must call a tool holding a personal access token needs it. Read only from this file and never derived from an event, so an outside party cannot choose the identity its trigger runs as. A system:* principal is refused (nothing can log in as one, so there is no credential to borrow), and the id is vetted against the same creation ceiling a task creation faces. Omitted, the run executes as system:config, which holds no per-user secrets. The task row's owner_user_id stays system:config either way — that is what reconciliation uses to tell its own rows from a user's.
scopenoCheap indexed narrowing — a repo name, a goal id.
whenno[path, op, value] clauses, ANDed, evaluated over the normalized payload. "Either/or" is spelled as two entries.
modenocoalesce (default) merges a burst into one run; per_event runs once per event.
enablednofalse reconciles the task to cancelled while leaving the lines in the file to document what it was — the same terminal state as deleting the entry, and the entry is not validated either (turning a task off must not first require fixing it).
descriptionnoFree text, stored on the row.
metadatanoExtra task metadata. Keys carrying run identity, job routing or engine-stamped provenance are refused, not stripped — a declaration free to write task_id would be a forgeable audit trail. access_profile and the timeout have their own fields.
bindnoExplicit ${event.<path>} → job_args bindings. Rarely needed: placeholders in run.prompt are compiled into this automatically.
job_typenoDefaults to agent_task_run; repo_ingest is the only other accepted value.
target_queuenoDefaults to agent_runs.
on_overlapnoskip (default), queue or cancel_previous.
debounce_secondsnocoalesce window. Default 30.0; 0 fires on the next loop tick.
max_delay_secondsnoCap on debounce extension, measured from the first event of the burst. Default 300.0, and never below debounce_seconds.
max_in_flightnoHow many of this task's jobs may be pending or running at once. Default 3.
max_fires_per_hournoPer-task storm cap. Default 12. Three times the cap in routing attempts within an hour auto-pauses the task.
allow_selfnoWhether an event caused by this very task's own run may fire it again. Default false.
max_chain_depthnoNarrows tasks.max_chain_depth for this task. It can never widen it.

An unknown key in an entry is refused, not ignored: a mistyped line in a
declaration that decides whether an unattended, tool-auto-approving turn runs
must not be silently dropped. Two entries sharing a name are refused for the
same reason rather than resolved last-one-wins — the name is the key, so one of
them would silently not exist.

Reconciliation semantics. name is the key, and everything follows from
that:

You doReconciliation does
Add an entryCreates the row.
Change an entryUpdates the row in place, keeping its id and run history. Changing the firing spec discards any pending arming (it was matched against a spec that no longer applies); changing job_type or target_queue cannot be updated in place and is a delete plus a create.
Remove an entry, or set enabled: falseCancels the row — it is not deleted. The history stays visible, and an in-flight run is left to finish exactly as your own cancel would leave it.
Rename an entryDelete plus create. There is no rename detection and deliberately none: two entries that swapped names could only be matched by guessing. The old name's row is cancelled and the new name gets a fresh one, with no history carried over.
Re-add a name you removedDeletes the cancelled tombstone and creates fresh, so a remove/re-add cycle cannot accumulate one row per cycle.
Pause a declared task, or let disable_after_failures disable itNothing. Reconciliation decides a task's existence and shape, never its activity — a paused declared task stays paused across edits and restarts, and is resumed with resume_task.

A bad entry costs different things at different times. At startup each
entry is compiled independently: one that fails is logged at ERROR and skipped,
and its existing row is left alone rather than cancelled, so a typo
introduced while editing one task cannot delete a different one. On reload
a tasks: edit is all-or-nothing: any compile error rolls the whole
section back to the last list that validated, re-reconciles against that, and
reports the section as failed.

Reloading. tasks: is REBUILD-classified, so editing declared: takes
effect on the next reload without a restart (SIGHUP, the admin endpoint, or
the auto_reload watcher). The caps in the same section are read live off the
config object. tasks.enabled is the exception — it is read once at startup,
and a reload that changes it raises a "restart required" caveat.

What ships by default. The default config carries three entries:
ingest-on-push (the built-in ingestion task — see
Webhooks), and gitea-review-on-pr /
gitea-review-on-request, both enabled: false because a review run posts to a
public pull request unattended. Turning those two on means adding the
gitea_pr plugin, defining the pr-reviewer access profile they name,
creating the gitea-review-bot account their run_as: names (with a
gitea_api_token user secret on it), and setting the plugin's
auto_post_on_review_comment: true — until that last one an unattended run
holds no gitea_* write tool and posts nothing, which makes it a working
kill-switch even with the entries enabled; see
gitea_pr. The minimal, marketing and
root flavor configs carry ingest-on-push alone; investigate declares none
and turns the task engine off entirely.

Routing. By default, scheduled fires land on the shared agent_runs job queue. Plugins that need per-user isolation can pass a per-user queue name at task creation (target_queue=f"agent_runs_{user_id}"). Be aware that each distinct queue name spawns its own processor task — don't multiply them casually.

Disabling at runtime. Set enabled: false and restart. Tasks persist in the DB and resume when re-enabled. To stop a single task without touching config, use task_engine.pause(id) or task_engine.cancel(id) from code.

See the task engine guide for the plugin-developer view and firing semantics.

webhooks

Push-notification webhook endpoint — lets Gitea/GitHub trigger ingestion automatically. See Webhooks for full setup.

webhooks:
  enabled: true
  secrets:
    - "${CODUMENTOR_WEBHOOK_SECRET}"
    - "${CODUMENTOR_WEBHOOK_SECRET_PREVIOUS}"

logging

Logging configuration:

Built-in log rotation. Codumentor can rotate the log file itself (a TimedRotatingFileHandler), independent of an external logrotate:

logging:
  level: INFO
  file: ./logs/codumentor.log
  rotation_enabled: true
  rotation_when: midnight    # "midnight", "H" (hourly), "D" (daily), "W0".."W6", "S", "M"
  rotation_interval: 1       # rotate every N of the above unit
  rotation_backup_count: 30  # keep this many rotated files
  rotation_utc: true         # compute rollover times in UTC
FieldDefaultDescription
rotation_enabledfalseEnable timed rotation of the log file.
rotation_when"midnight"Rollover unit (Python TimedRotatingFileHandler codes).
rotation_interval1Number of rotation_when units between rollovers.
rotation_backup_count30How many rotated files to retain; older ones are deleted.
rotation_utctrueUse UTC when deciding rollover boundaries.

LLM payload tracing. Full request dumps -- every message and tool schema of every model call -- are written to a separate, non-propagating logger, codumentor.trace.payload, which is off by default. The main log gets one summary line per call instead (LLM request (stream): messages=… content_chars=… tools=… tools_digest=…). Enable tracing for a debugging session with trace_payload: true, a logger_levels entry codumentor.trace.payload: DEBUG, or the environment variable CODUMENTOR_TRACE_PAYLOAD=1. The trace goes to its own size-capped file (JSON when json_logging is on, so scripts/diff_llm_payloads.py can read it):

FieldDefaultDescription
trace_payloadfalseWrite full LLM request payloads to the trace file.
trace_file<file stem>.trace.logTrace file path, next to the main log by default.
trace_max_bytes52428800 (50 MB)Size at which the trace file rotates.
trace_backup_count2Rotated trace files to keep.

JSON logging (for ELK/Splunk/Datadog — see also Deployment → JSON Logging):

FieldDefaultDescription
json_loggingfalseEmit structured one-line-JSON logs.
json_log_filenullSeparate file for JSON logs. If unset, JSON is written alongside the text log.
json_include_contexttrueInclude the per-record context dict (session id, etc.).
json_include_stack_infofalseInclude stack info on records that carry it.
json_include_process_infofalseInclude process/thread identifiers.
json_date_formatnullOverride the timestamp format.

The text file handler (and the JSON handler when enabled) is always configured when a log file path is set.