Kapso configuration reference: every key in config.yaml

Kapso reads a single YAML file. Every tunable value lives there, and nothing is configured through environment variables.

Where the config comes from

Kapso ships a packaged config.yaml and uses it unless you point somewhere else:

from kapso import Kapso

kapso = Kapso()                              # packaged config
kapso = Kapso(config_path="./my-config.yaml")  # yours

kapso doctor --config ./my-config.yaml
kapso learn mine --all --config ./my-config.yaml

Configuration and credentials are separate. Knobs — models, budgets, timeouts, gates — come from this file. Credentials never do: the coding-agent CLIs hold their own logins, and keys such as OPENAI_API_KEY are read from .env by the SDKs that need them.

Top-level keys

Key	What it controls
`default_mode`	Which entry in `modes` is active
`inference`	The CLI, model and effort behind non-coding model calls
`preflight`	Whether requirement checks run before a verb
`deployment`	The coding agent and model behind `deploy()`’s selector and adapter sessions
`defaults`	Embedding model, heartbeat and request timeout
`modes`	Named bundles of search, agent, feedback and knowledge settings
`learning`	The trajectory store, lesson bank, graders and update crew

default_mode

default_mode: GENERIC

Names the entry in modes used when nothing overrides it. Override per run with kapso evolve --mode MINIMAL or evolve(mode="MINIMAL").

inference

Routes model calls that are not coding-agent work: research, reranking and utilities.

The packaged config’s inference block is the base layer. An inference: block in your own config file deep-merges over it — override one key (say default.model) and the packaged roles and remaining defaults stay in force.

inference:
  default:
    cli: codex
    model: gpt-5.6-sol
    effort: xhigh
    sandbox: read-only
    timeout_seconds: 900
  roles:
    research:
      web_search: true
      timeout_seconds: 1800
    kg_rerank:
      effort: low
      timeout_seconds: 300

Key under `default`	What it does	Shipped value
`cli`	Which CLI runs the call	`codex`
`model`	Model that CLI is asked for	`gpt-5.6-sol`
`effort`	Reasoning effort	`xhigh`
`sandbox`	Filesystem access granted to the call	`read-only`
`timeout_seconds`	Per-call timeout	`900`

roles overrides default for one named role. Anything a role omits falls back to default, so kg_rerank above keeps cli: codex and only lowers effort and timeout.

Role	Purpose	Overrides
`research`	Deep web research	`web_search: true`, 1800s
`kg_rerank`	Rerank knowledge-graph hits	`effort: low`, 300s
`kg_navigate`	Navigate the graph	`effort: low`, 300s
`repo_memory`	Build repository memory	none, inherits `default`
`commit_message`	Write experiment commit messages	`effort: low`, 180s
`benchmark_utility`	Benchmark helper calls	`effort: low`, 600s

preflight

preflight:
  enabled: true
  live_model_probe: false

Key	What it does	Shipped value
`enabled`	Run requirement checks before a verb starts	`true`
`live_model_probe`	Also fire a one-token live call per CLI and model pair	`false`

These are the same checks kapso doctor reports. Leaving enabled: true is what makes a missing CLI fail in seconds instead of deep inside a run.

deployment

deployment:
  coding_agent: claude_code
  model: claude-opus-5

Key	What it does	Shipped value
`coding_agent`	The agent that runs the selector (for `AUTO`) and the adapter that rewrites a copy of the solution for its target	`claude_code`
`model`	The model that agent is asked for	`claude-opus-5`

The agent must be able to serve the model: a Claude model name on the codex agent is refused by a ChatGPT login. deploy(coding_agent=..., model=...) and kapso deploy --coding-agent override per call, and a deployment: block in your own config file layers over the packaged one key by key.

defaults

defaults:
  models:
    embedding: text-embedding-3-small
  budget:
    checkpoint_heartbeat_seconds: 60
  retry:
    request_timeout_seconds: 600
  inbox:
    enabled: true
    stop_grace_seconds: 120
    registry: "~/.kapso/campaigns.jsonl"

Key	What it does	Shipped value
`models.embedding`	Embedding model for knowledge search and memory	`text-embedding-3-small`
`budget.checkpoint_heartbeat_seconds`	How often a run writes its checkpoint and status	`60`
`retry.request_timeout_seconds`	Default request timeout	`600`
`inbox.enabled`	Let a blocked session ask you through the inbox and pause the campaign. See the inbox	`true`
`inbox.stop_grace_seconds`	How long a session that asked gets to end its own turn before the adapter ends it	`120`
`inbox.registry`	One line per launched campaign, so `kapso inbox` outside a campaign can list every one that waits	`~/.kapso/campaigns.jsonl`

modes

A mode is a named bundle of settings. Two ship: GENERIC and MINIMAL. MINIMAL differs mainly by turning knowledge search off and using shorter learner timeouts. Each mode carries six blocks.

search_strategy

search_strategy:
  type: generic
  params:
    idea_generation_model: claude-opus-5
    implementation_model: claude-opus-5
    auth_mode: oauth
    gate_failure_policy: warn
    ideation_gates: [research, experiment_history, repo_memory, leeroopedia]
    implementation_gates: [research, repo_memory, leeroopedia]

Key	What it does
`type`	Which search strategy runs the campaign
`params.idea_generation_model`	Model that proposes candidates
`params.implementation_model`	Model that writes the code
`params.auth_mode`	`oauth`, `api_key`, `auto` or `bedrock`
`params.gate_failure_policy`	What to do when an MCP gate is unavailable. `warn` continues
`params.ideation_gates`	MCP tools offered while designing a candidate
`params.implementation_gates`	MCP tools offered while implementing it

See Capability-aware MCP gates.

coding_agent and feedback_generator

Both take the same shape:

coding_agent:
  type: claude_code
  model: claude-opus-5
  debug_model: claude-opus-5
  agent_specific:
    auth_mode: oauth
    streaming: true

Key	What it does
`type`	`claude_code`, `codex`, `gemini`, `openhands` or `oss_claude_code`
`model`	Model for normal work
`debug_model`	Model used when an experiment is being debugged
`agent_specific.auth_mode`	`oauth` uses the CLI’s stored login, `api_key` uses `ANTHROPIC_API_KEY`, `auto` takes either (never Bedrock), `bedrock` runs against Amazon Bedrock with AWS credentials and models named by inference profile id
`agent_specific.aws_region`	The Bedrock region; required with `auth_mode: bedrock`, and read from the config only, never from `AWS_REGION`
`agent_specific.streaming`	Stream the agent’s output

knowledge_search

knowledge_search:
  type: kg_graph_search
  enabled: true
  preset: DEFAULT

Key	What it does
`type`	`kg_graph_search` for hybrid vector and graph search, or `kg_llm_navigation`
`enabled`	Whether campaigns query the knowledge graph. `MINIMAL` ships this `false`
`preset`	Named retrieval preset

See Search backends.

retry

retry:
  max_attempts: 2
  initial_delay_seconds: 5
  max_delay_seconds: 60
  multiplier: 2
  jitter: true

Bounded exponential backoff for transient model failures. See Model routing and retries.

learner

Two sub-blocks, ingestor and merger, controlling learn_knowledge(). Both take a model, an auth_mode and a timeout. ingestor additionally takes cleanup, cleanup_staging, fail_on_validation_errors and github_repo_visibility.

learning

Everything about trajectory learning: mining finished campaigns into an evidence-priced lesson bank.

Key	What it controls
`trajectory_store`	`local` path and optional `remote` for imported campaigns
`bank`	`local_path` of the bank repository
`serving`	Whether banked lessons are served into campaigns
`retriever`	`probe_budget` for lesson retrieval
`harvest`	Whether finished campaigns are harvested automatically
`mining`	How trajectories are mined into their derived views
`graders`	The grader suite settings
`update_crew`	The crew that folds lessons in: roles, repair rounds, timeouts
`codify`	The codify pipeline
`develop`	The development regime
`behavior`	Behavior scenarios
`ab`	A/B arm settings
`import_report_dir`	Where import reports are written
`status_dir`	Where status files are written

Shipped values worth knowing:

learning:
  trajectory_store:
    local: ~/.kapso/trajectories
    remote: null
  bank:
    local_path: ~/.kapso/bank.git
  serving:
    enabled: false
  update_crew:
    default_version: crew_v4

The store and the bank are Kapso’s own state and live under ~/.kapso, outside the project you run from, so a campaign’s --data-dir and seed copy never pick them up.

learning.serving.enabled ships as false. Until you turn it on, campaigns do not read from the lesson bank, so banked lessons have no effect on evolve().

update_crew.default_version is the version learn() uses when you do not pass learner_version.

CLI

Commands that accept —config

Python API

Passing config_path to Kapso()

Related pages: CLI · Python API · CLI Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

​Where the config comes from

​Top-level keys

​default_mode

​inference

​preflight

​deployment

​defaults

​modes

​search_strategy

​coding_agent and feedback_generator

​knowledge_search

​retry

​learner

​learning

​Related

CLI

Python API

Where the config comes from

Top-level keys

default_mode

inference

preflight

deployment

defaults

modes

search_strategy

coding_agent and feedback_generator

knowledge_search

retry

learner

learning

Related