config.yaml¶

config.yaml defines models, providers, projects, entrypoints and skills. Nearly every value is a Jinja template reading an environment variable, so most deployments only edit .env and never touch the YAML.

The authoritative copy of the defaults ships in the package at src/core/defaults/config.yaml.

Resolution¶

BaseConfig (src/core/config.py) loads three layers:

1. Bundled defaults — core/defaults/config.yaml, always present.
2. <cwd>/config/config.yaml — if present, replaces the bundled defaults entirely.
3. <cwd>/config/config.custom.yaml — if present, deep-merged on top.

The recommended pattern is to leave the bundled defaults alone and write only the keys you change into config/config.custom.yaml, so upgrades keep bringing you new defaults.

projects is an entity section: when your overlay defines it, projects that exist only in the bundled defaults (i.e. default) are pruned rather than merged, so placeholders stay out of your project list. All other sections merge normally.

The same layering applies to prompts.yaml.

Value syntax¶

models:
  large: "@jinja {{env.LLM_MODEL_LARGE or 'openai:gpt-4.1'}}"

providers:
  github:
    token: "@jinja {{ env.get('GITHUB_TOKEN', '') }}"

projects:
  default:
    pullrequests:
      github:
        token: "@jinja {{ this.providers.github.token }}"   # cross-reference

• @jinja values are rendered by Dynaconf at load time; both env.NAME and env.get('NAME', '') forms are used.
• this.<dotted.path> references another value in the same file — this is how a provider is defined once and reused per project.
• Rendering produces strings, so booleans are read through BaseConfig.get_bool() (true, 1, yes, on). Write plain true / false in your own YAML.
• Dynaconf environments are disabled — there is no [development] / [production] layering, and DYNACONF_ENV has no effect. Use separate .env files or overlays instead.

Sections¶

core¶

models¶

Two named slots that agents reference via this.models.*. Values are Pydantic AI model strings.

models:
  large: "anthropic:claude-sonnet-5"
  small: "anthropic:claude-haiku-4-5"

openai: targets the Responses API; use openai-chat: for Chat Completions semantics or a gateway that only speaks that API. Temperature and token limits are per-agent, see agents.

providers¶

Credentials defined once and referenced from projects. Every provider has a mock flag that returns canned data instead of calling the API.

The matching environment variables are listed in environment variables. bitbucket.api_url defaults to https://api.bitbucket.org/2.0; the other URLs default to empty.

When a pull request provider clones its repository, the clone URL is validated before the token is used: it must be https:// and its host (including any port) must match the provider's configured host (devops.url, gitlab.api_url, or the web host derived from github.api_url / bitbucket.api_url). URLs that embed credentials are always rejected. allowInsecureCloneUrl: true is a development-only override that additionally permits http://; the host check still applies.

projects¶

A project ties one git checkout to the providers that serve its pull requests, issues and pipelines. The bundled defaults ship a single project named default.

projects.<name>.git

Provider slots — each maps a provider name to that provider's settings:

Delete the slots you do not use — an unconfigured provider is simply not offered to the agent. From code, access goes through ProjectConfig (src/core/project_config.py):

from core.config import get_default_config

project = get_default_config().get_default_project_config()
project.get_git_config()
project.get_provider_config("pullrequests", "github")

slack¶

Attachment forwarding is opt-in on purpose: it sends private Slack files into the LLM context. Overriding suggestedPrompts replaces the whole list.

http, agui, openai, nats, cli¶

These mirror their environment variables one-to-one — see environment variables. http.server.* configures the shared server used by the AG-UI and OpenAI-compatible entrypoints; agui.server.enabled and openai.server.enabled decide whether it starts at all.

Both entrypoints run the agent, so authentication is fail-closed. An enabled entrypoint needs agui.server.apiKeys / openai.server.apiKeys (AGUI_API_KEYS / OPENAI_API_KEYS, a comma-separated string or a YAML list of Bearer tokens). If the value is empty, missing or has any other type, startup aborts with a configuration error instead of serving the agent openly. To run without authentication on purpose, set agui.server.allowUnauthenticated / openai.server.allowUnauthenticated (AGUI_ALLOW_UNAUTHENTICATED / OPENAI_ALLOW_UNAUTHENTICATED) to true. This is unsafe outside a trusted network: anyone who reaches the port gets repository access, the registered tools and your LLM spend.

skills¶

Skills are Python modules that register extra agent tools through the hook system. load_skills() imports them at startup.

skills:
  enable:
    - skills.scheduler
    - mycompany_skills.deploy
  search_paths:
    - /opt/dev-agents/custom-skills

agents¶

subagents¶

When the claude extra is installed and subagents.claude_code.cli_path is set, the chat agent uses the Claude Code research tool; otherwise it falls back to the built-in code research subagent.

A minimal overlay¶

# config/config.custom.yaml
models:
  large: "anthropic:claude-sonnet-5"
  small: "anthropic:claude-haiku-4-5"

projects:
  backend:
    git:
      path: "/code/backend"
      defaultBranch: "develop"
      autoPull: true
    pullrequests:
      github:
        api_url: "@jinja {{ this.providers.github.api_url }}"
        owner: "@jinja {{ this.providers.github.owner }}"
        repo: "@jinja {{ this.providers.github.repo }}"
        token: "@jinja {{ this.providers.github.token }}"
        mock: false

agents:
  gitchatbot:
    timeoutSeconds: 120

Because projects is an entity section, this leaves exactly one project — backend.

Check what loaded¶

python -c "
from core.config import get_default_config
c = get_default_config()
print('models.large:', c.get_value('models.large'))
print('projects:', c.get_available_projects())
print('git path:', c.get_default_project_config().get_git_config().get('path'))
"

An empty value means the environment variable behind it is unset.

Next steps¶

• Environment variables
• prompts.yaml
• Integrations
• Hooks and skills