Install Kapso and verify your setup with kapso doctor

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

You need	Why	Checked by
Node.js 18 or newer	Both coding-agent CLIs are npm packages	`node`
Codex CLI, logged in	Research, judging and utility calls	`codex authenticated`
Claude Code CLI, logged in	Ideation and implementation in the default `GENERIC` mode	`claude authenticated`
Python 3.10 or newer	The `leeroo-kapso` package	—
An OpenAI API key	Embeddings for knowledge search and memory. Not used for generation	`OPENAI_API_KEY (embeddings)`
Git	Kapso commits every experiment to a branch	`git`

Install Kapso

Install and log in to the coding-agent CLIs

npm install -g @openai/codex
codex login

npm install -g @anthropic-ai/claude-code
claude auth login

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

Add an OpenAI key for embeddings

Create a .env file in the directory you will run Kapso from:

echo 'OPENAI_API_KEY=sk-...' >> .env

This key is used only to embed text for knowledge search and memory. Generation runs through the CLIs above.

Install the package

pip install leeroo-kapso

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:

git clone https://github.com/leeroo-ai/kapso.git
cd kapso
conda create -n kapso_conda python=3.12
conda activate kapso_conda
pip install -e .

Verify the machine is ready

kapso doctor

Every required check must read [OK ] before you run anything else.

How do I check my setup?

kapso doctor reports what your config requires, and names one fix for anything missing:

kapso doctor

kapso doctor
====================================================================
  [OK ] node
  [OK ] codex CLI
  [OK ] codex authenticated
  [OK ] claude CLI
  [OK ] claude authenticated
  [OK ] git
  [OK ] OPENAI_API_KEY (embeddings)
  [OK ] deploy target docker
  [-- ] deploy target modal
         needed by  only needed for deploy(strategy=DeployStrategy.MODAL)
         fix        pip install modal && modal token new
====================================================================
Required checks passed (9 checked). 1 optional item(s) marked [-- ] only limit features you may not need.

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

Marker	Meaning
`[OK ]`	Present and working
`[FAIL]`	Required by your config and missing. The run will stop
`[-- ]`	Optional. Its absence only removes a feature you may not need

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:

kapso doctor research

kapso doctor research
====================================================================
  [OK ] node
  [OK ] codex CLI
  [OK ] codex authenticated
====================================================================
Required checks passed (3 checked).

kapso doctor evolve

kapso doctor evolve
====================================================================
  [OK ] node
  [OK ] claude CLI
  [OK ] claude authenticated
  [OK ] git
====================================================================
Required checks passed (4 checked).

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.

kapso doctor evolve --models

--models spends a small number of real tokens. The plain doctor makes no model calls.

Each agent block in the config carries an auth_mode. The shipped default is oauth, which uses the CLI’s own stored login:

`auth_mode`	Credential used
`oauth`	The CLI’s stored login from `claude auth login`
`api_key`	`ANTHROPIC_API_KEY` from your environment
`auto`	Either, whichever is present; never Bedrock
`bedrock`	AWS credentials (`AWS_BEARER_TOKEN_BEDROCK`, an access key pair, or `AWS_PROFILE`) with `aws_region` set in the config; models are named by Bedrock inference profile id. See coding agents

For non-interactive environments such as CI, put a token in .env instead of logging in:

CLAUDE_CODE_OAUTH_TOKEN=...
CODEX_API_KEY=...

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:

bash scripts/start_infra.sh

Service	Purpose	URL	Credentials
Weaviate	Vector store for embeddings	`http://localhost:8080`	Anonymous
Neo4j	Graph store for relationships	`http://localhost:7474`	`neo4j` / `password`

bash scripts/stop_infra.sh              # stop, keep the data
bash scripts/stop_infra.sh --volumes    # stop and wipe the data

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.

MLE-Bench
ALE-Bench
RelBench

Kaggle competition problems. Needs Git LFS.

git clone https://github.com/openai/mle-bench.git
cd mle-bench
git lfs install
git lfs fetch --all
git lfs pull
pip install -e .
cd ..

pip install -r benchmarks/mle/requirements.txt

See MLE-Bench for how to run it.

AtCoder algorithmic optimization problems. Needs Docker and libcairo2-dev.

git clone https://github.com/SakanaAI/ALE-Bench.git
cd ALE-Bench
pip install .
pip install ".[eval]"
bash ./scripts/docker_build_202301.sh $(id -u) $(id -g)
cd ..

See ALE-Bench for how to run it.

Predictive tasks over relational databases. Installed from PyPI.

pip install relbench

See RelBench for how to run it.

Optional: Leeroopedia MCP

Leeroopedia is a curated knowledge base of ML and AI frameworks. Kapso agents query it during ideation and implementation to look up APIs, build plans and diagnose failures.

pip install leeroopedia-mcp

Get a key at app.leeroopedia.com, then add it to .env:

LEEROOPEDIA_API_KEY=kpsk_...

Troubleshooting

doctor says a CLI is missing but I just installed it

Global npm binaries have to be on your PATH. Confirm the shell can see them:

which codex claude node

If npm install -g wrote somewhere outside your PATH, npm prefix -g shows where.

doctor says a CLI is not authenticated

The login is stored per machine and expires. Re-run it:

codex login
claude auth login

Codex stores its login at ~/.codex/auth.json. Claude Code answers claude auth status.

Weaviate or Neo4j will not start

Check the container logs:

docker compose -f services/infrastructure/docker-compose.yml logs

Ports 8080, 50051, 7474 and 7687 must be free. If one is taken, change the mapping in services/infrastructure/docker-compose.yml.

A run fails partway through on a model error

Probe the models directly with kapso doctor evolve --models — see How do I confirm my models are actually reachable?

Working through a coding agent

If Claude Code, Codex or OpenCode will be running Kapso for you, copy the Kapso skill into the project as well. It 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.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Install Kapso and verify your setup with kapso doctor

Prerequisites

Install Kapso

How do I check my setup?

What the markers mean

How do I check just one command’s requirements?

How do I confirm my models are actually reachable?

Optional: Knowledge-graph backends

Optional: Benchmarks

Optional: Leeroopedia MCP

Troubleshooting

Working through a coding agent

Quickstart

CLI reference

Kapso skill for coding agents

​Prerequisites

​Install Kapso

​How do I check my setup?

​What the markers mean

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

​How do I confirm my models are actually reachable?

​Using API keys instead of a CLI login

​Optional: Knowledge-graph backends

​Optional: Benchmarks

​Optional: Leeroopedia MCP

​Troubleshooting

​Working through a coding agent

​Related

Quickstart

CLI reference

Kapso skill for coding agents

Prerequisites

Install Kapso

How do I check my setup?

What the markers mean

How do I check just one command’s requirements?

How do I confirm my models are actually reachable?

Using API keys instead of a CLI login

Optional: Knowledge-graph backends

Optional: Benchmarks

Optional: Leeroopedia MCP

Troubleshooting

Working through a coding agent

Related