> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leeroo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Kapso build and watch it

> Launch a build in a session of its own with kapso build --detach, follow it with kapso watch, and read the summary block it ends with: COMPLETED, or WAITING ON YOU.

A build takes tens of minutes to hours. Launch it detached, follow it with
`kapso watch`, and come back for the summary block.

## Before the launch

```bash theme={null}
kapso doctor build
```

Every required row must read `[OK ]`. These are the checks the build runs
itself before it spawns a session, so a missing login fails here in
seconds rather than an hour in. See [Install](https://docs.leeroo.com/docs/installation.md).

## Launch

```bash theme={null}
kapso build --brief kapso-brief.md --evaluation evaluation --data data --repo repo --output campaign --detach
```

| Flag | What it does |
| - | - |
| `--brief` | The brief file. `--goal "..."` is the one-line form; `--goal-file` a plain-text objective |
| `--evaluation` | Your evaluator, copied to `kapso_evaluation/` and protected |
| `--data` | Your data, copied to `kapso_datasets/` |
| `--repo` | The starting repository, a path (copied, never modified) or a GitHub URL (cloned) |
| `--output` | The campaign directory, empty for a fresh build: every branch and the record live there |
| `--budget-minutes`, `--budget-experiments`, `--budget-usd`, `--budget-reserve-minutes` | The budget; a flag wins over the brief's `Budget` line |
| `--detach` | Start in a session of its own and return at once; `--log` names the log, which must lie outside `--output` |

`--detach` prints what you need to follow the run and nothing else:

```text theme={null}
kapso build started in a session of its own (pid 41213)
  log:     /home/me/churn/campaign.log
  status:  /home/me/churn/campaign/.kapso/status.json
  follow:  kapso watch /home/me/churn/campaign --follow
  inbox:   kapso inbox /home/me/churn/campaign
```

The run outlives the shell that started it, a coding agent's tool call
included; no `nohup` or `setsid` is needed. Without `--detach` the build
runs in the foreground and prints the summary block when it returns. A
detached launch also leaves a receipt beside the log,
`campaign.launch.json`, so a watch started before the status file exists
can tell a campaign still starting from one that died first.

The same from Python, which blocks until the build returns:

```python theme={null}
from kapso import Kapso, Brief, Budget

solution = Kapso().build(
    Brief.read("kapso-brief.md"),
    evaluation="evaluation", data="data", repo="repo", output="build",
    budget=Budget(minutes=60),
)
```

## Watch

```bash theme={null}
kapso watch campaign --follow     # re-render on each heartbeat until the build ends
kapso watch campaign              # once
kapso watch                       # every campaign alive or waiting on you, newest first
kapso watch campaign --json       # the status file as it is
kapso trace campaign              # the attempts and the record, after the fact
```

```text theme={null}
┌─ build /home/me/trading/campaign/.kapso/status.json ──────────────────┐
│ RUNNING ♥ 12s ago      pid 41213                                       │
│ harness: trading 0.1.0 (83b6c0b60d6a)                                  │
│ served: mine at a9ddad3d302d, measured by you                          │
│ phase: implementation — 6m elapsed                                     │
│ budget: ████████░░░░░░░░░░░░ 17/40 min                                 │
│ iteration 1                                                            │
│ recent:                                                                │
│   18:25 iteration 1 started (budget 8%)                                │
└────────────────────────────────────────────────────────────────────────┘
```

The status file appears within seconds of the launch, in phase `setup`
while the workspace is seeded and repo memory is bootstrapped (minutes),
then `ideation`, `implementation`, `evaluation`, `feedback`, one round per
experiment. The header names the harness and the sources from the first
second; `kapso watch` shows the phase, the iteration, the best and the
latest score, the budget bar, and the last lines of output. `DEAD` means
the process is gone; `STALLED` means three heartbeats were missed. Both are
resumed the same way, see [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md).
A campaign that failed shows its `error` line.

Before the status file exists, a detached launch's receipt tells the two
cases apart: `starting (pid 41213, launched 9s ago; log: …)` while the
child lives, and `stopped before writing a status; the log says why:
/home/me/trading/campaign.log` once it is gone (exit 1; `--follow` stops
waiting). With no argument, `kapso watch` lists the campaigns the launch
registry knows that are alive or waiting on you, and the learns and
ingests running, one line each; `--all` lists every campaign with its
state.

When the build has returned, `kapso trace campaign` lays the record out:
every attempt with its sessions and runs, the lessons served, what was
voided and on what evidence, the sessions that failed, the delivered
candidate. See [Read the record](https://docs.leeroo.com/docs/build/trace.md).

## The summary block

A build ends in one of two blocks:

```text theme={null}
============================================================
COMPLETED
============================================================
Solution for:    Raise the churn model's out-of-sample ROC AUC above 0.85
Campaign:        /home/me/churn/campaign
Candidate:       generic_exp_3 @ 4f1c0e2a…
Score:           0.8614
Goal achieved:   True
Stopped:         goal_achieved
Experiments:     3 this run, 3 in all
Cost:            $1.934
```

`Stopped` is `goal_achieved`, `max_iterations`, or `budget_exhausted`
with the dial that ran out; `Candidate` says `none succeeded` when no
candidate produced a valid measurement. Or:

```text theme={null}
============================================================
WAITING ON YOU
============================================================
Solution for:    Raise the churn model's out-of-sample ROC AUC above 0.85
Campaign:        /home/me/churn/campaign
Candidate:       none succeeded
Goal achieved:   False
Stopped:         waiting_for_user
Experiments:     1 this run, 1 in all
Cost:            $0.412
Waiting on you:
  #1  env:OPENAI_API_KEY
Reply with:  kapso inbox reply "…"   (inside /home/me/churn/campaign)
Any time:    kapso inbox /home/me/churn/campaign
```

A session needed something only you can provide. The campaign has paused,
not failed (the exit code is 0); see [The inbox](https://docs.leeroo.com/docs/build/inbox.md).

## What is in the campaign directory

```text theme={null}
campaign/
├── predict.py, …             the delivered candidate, checked out
├── kapso_evaluation/         your evaluator, or the one the campaign built
├── kapso_datasets/           your data
└── .kapso/
    ├── solution.json         the record: what Solution.open reads
    ├── status.json           what kapso watch reads
    ├── run_state.json        the checkpoint a resume continues from
    ├── launch.json           every flag of the launch
    ├── sessions/<session>/   each session's record (session.json: what it was staged with, its runs) and stream
    ├── serving/              what the build was served, and the pull log of every bank read
    ├── verification/<branch>/  the diff, the evaluation output and the verdict of each verified attempt
    ├── experiment_history.json, evaluation_registry.json, inbox.jsonl
    └── …
```

One git branch per experiment, `generic_exp_N`; `main` is the seed. See
[Review the result](https://docs.leeroo.com/docs/build/review.md) and [Read the record](https://docs.leeroo.com/docs/build/trace.md).

## Related

> [card] [The inbox](https://docs.leeroo.com/docs/build/inbox.md)
>
> When the campaign waits on you

> [card] [Review the result](https://docs.leeroo.com/docs/build/review.md)
>
> The Solution and the record

> [card] [Read the record](https://docs.leeroo.com/docs/build/trace.md)
>
> Every attempt, session and run, after the fact

> [card] [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md)
>
> Continue a build, give it more

Related pages: [The inbox](https://docs.leeroo.com/docs/build/inbox.md) · [Review the result](https://docs.leeroo.com/docs/build/review.md) · [Read the record](https://docs.leeroo.com/docs/build/trace.md) · [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md) · [CLI reference](https://docs.leeroo.com/docs/reference/cli.md#kapso-build)

Kapso is an open-source framework by [Leeroo](https://leeroo.com) that builds software toward measurable goals through experiment campaigns. Source code: [github.com/Leeroo-AI/kapso](https://github.com/Leeroo-AI/kapso) · Install: `pip install leeroo-kapso` · Every page as plain text: [llms.txt](https://docs.leeroo.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.