Codumentor logo Codumentor

Configuration

Codumentor is configured through a YAML configuration file, typically named codumentor.yaml. This file controls various aspects of the system including repositories to analyze, file patterns to include/exclude, 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. 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.

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.

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 by default — all known file types are included
# 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
  shell_always_allow: false
  search_concurrency: 5

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 self-hosted AI coworker."
    hu: "Önállóan üzemeltethető AI munkatárs."
  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"

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()"]

Workspace Isolation Plugin

The workspace isolation plugin sandboxes each conversation session using Linux bubblewrap with overlay filesystems. It requires bubblewrap (compiled with overlay support), an overlayfs-capable kernel, and — on Ubuntu 24.04+ — an AppArmor profile; 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.

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 (default: [] — empty)

When empty (the default), 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).

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

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:

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:

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

speech

Speech-to-text / text-to-speech service used by the read_aloud message action 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 lights 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 / the Telegram bot: a per-user ${secret:...} only resolves inside an agent turn, so it cannot drive the out-of-turn web read-aloud call.
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:

api

OpenAI-compatible API server configuration:

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:

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.

scheduler

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

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

scheduler:
  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_schedules_per_user: 100
  default_timezone: "UTC"
FieldTypeDefaultDescription
enabledbooltrueMaster switch. When false, the scheduler loop never starts and schedule_* operations will fail. Existing schedules 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 schedules up to this bound.
disable_after_failuresint5After this many consecutive infrastructure failures (e.g. database is locked on enqueue), the schedule is auto-disabled and its status becomes disabled. Handler exceptions do not count — they mark the fired job failed, not the schedule.
max_catchup_agefloat86400.0If the scheduler 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_schedules_per_userint100Cap on active+paused schedules per owner_user_id. Protects against unbounded growth if users can create schedules interactively.
default_timezonestr"UTC"Default IANA timezone for schedules that don't specify one.

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 schedule 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. Schedules persist in the DB and resume when re-enabled. To stop a single schedule without touching config, use scheduler.pause(id) or scheduler.cancel(id) from code.

See Scheduler 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.

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.