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
`gates`	Where the hosted MCP gates live
`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.

gates

gates:
  leeroopedia:
    url: "https://mcp.leeroopedia.com/mcp?token={LEEROOPEDIA_API_KEY}"
    tool_timeout_seconds: 600

The hosted MCP gates (see MCP gates). Bundled gates run in-process and have no entry here.

Key	What it does	Shipped value
`url`	The server’s streamable-HTTP address. A `{VAR}` placeholder is filled from the gate’s required environment variable when a session launches, so the key rides on the URL without ever being written into the config or the campaign tree	`https://mcp.leeroopedia.com/mcp?token={LEEROOPEDIA_API_KEY}`
`tool_timeout_seconds`	How long a session waits on one tool call. Both CLIs default to 60 seconds, which cuts off Leeroopedia’s agentic tools (`build_plan`, `verify_code_math`) mid-answer	`600`

Sessions connect to Leeroopedia’s hosted server directly; there is nothing to install.

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: null
  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`	The OpenAI embedding model for semantic search over past experiments (`search_similar_experiments`). `null` turns it off: the experiment store is recency-only and no `OPENAI_API_KEY` is needed. Set it (for example `text-embedding-3-small`) to turn it on; `kapso doctor evolve` then checks for the key	`null`
`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. 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]
    cost:
      enabled: false
      estimator: null
      cap_per_candidate: null
      campaign_budget: null
      unit: credits
      weight: 0.0

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
`params.cost.enabled`	Enable platform-cost estimation, admission checks, and selection; default `false`
`params.cost.estimator`	Module-qualified caller-owned estimator; required when enabled
`params.cost.cap_per_candidate`	Maximum estimate accepted for one candidate, in `unit`; `null` is unlimited
`params.cost.campaign_budget`	Campaign platform budget, using measured cost when available and estimates otherwise; `null` is unlimited
`params.cost.unit`	Shared estimate and measurement label; default `credits`, with no conversion
`params.cost.weight`	Non-negative platform-cost penalty in selection; default `0.0`

The packaged cost defaults live in defaults.search_strategy.params.cost and are inherited by every mode. Override individual keys under modes.<mode>.search_strategy.params.cost. Cost-enabled runs require the generic strategy and budget.fidelity.mode: off. Platform cost settings are separate from model spend in USD controlled by evolve(cost_budget=...). See Capability-aware MCP gates. See Cost-aware selection for the estimator contract, measured-cost manifest, admission lifecycle, and resume checks.

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`, `openai_compatible`, `oss_claude_code` or `vertex_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`	Tee the session’s live transcript to the console; every session runs on the event stream regardless, so cost, tool calls and the session id are recorded either way
`agent_specific.base_url`	OpenAI-compatible endpoint URL for `openai_compatible`
`agent_specific.api_key_env`	Environment variable containing the endpoint key (default `OPENAI_API_KEY`)

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
`params.embedding_base_url`	Config-only endpoint for `kg_graph_search` embeddings. Defaults to the OpenAI URL in `agents.yaml`; environment URL overrides are ignored. Requires HTTPS, except for loopback hosts.

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 cli, a model, an auth_mode, an effort and a timeout (shipped: claude_code, claude-opus-5-5, oauth, xhigh, null), plus an agent_specific map (shipped empty) that is passed to the agent. cli names the coding agent that runs the sessions: claude_code with the first-party login that auth_mode selects, or vertex_claude_code for an open model on Vertex AI, whose settings (vertex_project, vertex_location) go in agent_specific; on that agent effort is applied as the open model’s reasoning_effort (Vertex accepts minimal to max for GLM 5.2; xhigh is sent as max); see Coding Agents. effort is the reasoning effort of every learning session, pinned here so a session never inherits the effort from the machine’s own Claude settings. timeout is a deadline in seconds; null, the default, means a phase runs until it finishes. ingestor additionally takes cleanup, cleanup_staging, fail_on_validation_errors, publish_workflows and github_repo_visibility. publish_workflows (off by default) publishes each extracted Workflow as a runnable GitHub repository after the pages have been validated; gh authenticates with GH_TOKEN, which the preflight requires when publishing is on. Off, a Workflow page keeps a placeholder in its GitHub URL section. A failed phase stops the run: learn_knowledge() raises rather than returning a partial result as a success. A run stages its clone, phase reports and pages under <wiki_dir>/_staging/<repo>/<branch> and marks each finished phase, so a run that stopped continues from the first unfinished phase when the same source is learned again; cleanup removes the clone once a run completes, cleanup_staging the whole directory. Learning sessions hold five file tools (Read, Write, Edit, Glob, Grep) plus the knowledge tools and nothing else, so they cannot run commands, reach the network or delegate; only the publishing session also gets Bash, for git and gh.

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

​gates

​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

gates

deployment

defaults

modes

search_strategy

coding_agent and feedback_generator

knowledge_search

retry

learner

learning

Related