Skip to main content
Kapso sends every model call through a coding-agent CLI. Install those CLIs and log in before installing the Python package — on its own the package cannot reach a model, and kapso evolve will stop in seconds rather than fail deep inside a run.

​
Prerequisites

​
Install Kapso

1

Install and log in to the coding-agent CLIs

Both logins are interactive and open a browser. To authenticate without a browser, see Using API keys instead of a CLI login.
2

Optional: an OpenAI key for embeddings

Only the knowledge graph and semantic search over past experiments embed text, and generation never touches the OpenAI API. Nothing in a stock install needs the key. When you turn either on (a kg_index, learn_knowledge, or models.embedding in your config), put the key in a .env file in the directory you run Kapso from:
3

Install the package

The package is leeroo-kapso. The PyPI package named kapso is an unrelated WhatsApp tool that installs a kapso command of its own and shadows this one; if it is present, pip uninstall kapso first.To work from a source checkout instead:
4

Verify the machine is ready

Every required check must read [OK ] before you run anything else.
Leeroopedia is a hosted knowledge base of ML and AI frameworks. With a key in .env, every campaign session can ask it how a framework actually behaves, have its plan reviewed, pull documented hyperparameter ranges and diagnose a failed run. There is nothing to install: sessions connect to Leeroopedia’s hosted MCP server. Sign up at app.leeroopedia.com (new accounts get $20 of free credit), copy your key, and add it:
kapso doctor confirms the gate is live. Without a key the campaign still runs; the launch banner says the gate is off and how to turn it on. What each node consulted, and the credits used, appear in kapso watch --tree and the campaign’s final summary. See MCP gates for what the agent is told about it.

​
How do I check my setup?

kapso doctor reports what your config requires, and names one fix for anything missing:
Your own list will be longer or shorter than this one. It is derived from your config, so enabling knowledge search adds Weaviate and Neo4j rows, and configuring a lesson bank adds a remote-reachability row. These are the same checks each verb runs before it does any work, so doctor cannot disagree with what a run will do. The command exits non-zero when a required item is missing, which makes it usable in CI.

​
What the markers mean

Each failing item prints up to three lines: reason for what is wrong, needed by for the config key that wants it, and fix for the command that resolves it.

​
How do I check just one command’s requirements?

Name a verb to narrow the report to that verb’s own requirements. Requirements follow your config, so a verb that never calls Codex is never asked for it:
The five verbs are research, learn_knowledge, evolve, learn and deploy. With no verb, doctor reports the union of all five.

​
How do I confirm my models are actually reachable?

Add --models to fire a one-token live call per configured CLI and model pair. A revoked login, or a model your plan does not include, surfaces here in seconds instead of hours into a campaign. A usage cap on a model you can serve does not: a one-token probe passes until the cap is hit.
--models spends a small number of real tokens. The plain doctor makes no model calls.

​
Using API keys instead of a CLI login

Each agent block in the config carries an auth_mode. The shipped default is oauth, which uses the CLI’s own stored login: For non-interactive environments such as CI, put a token in .env instead of logging in:

​
Optional: Knowledge-graph backends

learn_knowledge() and kapso index_kg store into a local Weaviate and Neo4j. Both run in Docker. From a source checkout:
The stack runs Weaviate 1.39. If your volumes were created by an older stack (Weaviate 1.27), note that Weaviate supports upgrading one minor version at a time. The index is rebuilt from your wiki pages, so the simplest path is to wipe it and re-index: bash scripts/stop_infra.sh --volumes, bash scripts/start_infra.sh, then run kapso index_kg again. kapso doctor reports both as Weaviate (localhost:8080) and Neo4j (localhost:7687) when your config enables knowledge search.

​
Optional: Benchmarks

The benchmark harnesses live in the source checkout under benchmarks/ and each needs its upstream repository installed first.
Kaggle competition problems. Needs Git LFS.
See MLE-Bench for how to run it.

​
Troubleshooting

Global npm binaries have to be on your PATH. Confirm the shell can see them:
If npm install -g wrote somewhere outside your PATH, npm prefix -g shows where.
The login is stored per machine and expires. Re-run it:
Codex stores its login at ~/.codex/auth.json. Claude Code answers claude auth status.
Check the container logs:
Ports 8080, 50051, 7474 and 7687 must be free. If one is taken, change the mapping in services/infrastructure/docker-compose.yml.
Probe the models directly with kapso doctor evolve --models — see How do I confirm my models are actually reachable?

​
Set up through your coding agent

Paste this into Claude Code, Codex or OpenCode and it walks the steps above with you, hands you the sign-in links, asks for the keys instead of hunting for them, and verifies with kapso doctor:
The last step installs the Kapso skill, which has the agent run kapso doctor first, name the right package, and launch campaigns in the background with the handoff you need.

Quickstart

Run your first campaign

CLI reference

Commands, modes and flags

Kapso skill for coding agents

Let your coding agent run Kapso correctly
Related pages: Quickstart · CLI reference · Kapso skill for coding agents · What is Kapso 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.