harnesses.yaml
harnesses.yaml has two sections: harnesses: declares the harness profiles that agent tasks select, and the optional profiles: declares the agent profiles, the model tiers a task selects with profile:.
Kraft reads the file again at each agent launch, so an edit reaches the next launch without a restart. A task whose harness profile is missing or disabled, or whose harnesses.yaml cannot be read, stops and waits for you, with the reason in its session log. Kraft never falls back to another harness profile unless the task declares a fallback: list.
harnesses: harness profiles
A harness profile is a configured instance of an agent-runtime provider: the executable to run and the runtime options to start from. A harness profile selects only from what its provider supports. Every agent task's harness: names a harness profile here, never a provider directly.
harnesses:
codex:
provider: codex
enabled: true
executable: codex
defaults:
effort: medium
claude:
provider: claude
enabled: true
executable: claude
defaults:
model: sonnet
| Field | Type | Default | Meaning |
|---|---|---|---|
<harness id> | string | required | The name a task's harness: selects: a lowercase letter, then lowercase letters, digits, _ and -. |
provider | string | required | The provider this harness profile configures: claude, codex, cursor, opencode, gemini, antigravity or amp. See Agent harnesses. |
enabled | boolean | true | false takes the harness profile out of service, and a task selecting it stops and waits for you. |
executable | string | the provider's own command | The command to launch when it differs from the provider's default; the provider's own subcommand (codex exec) is kept after it. |
defaults | mapping | {} | The lowest-precedence runtime options. See defaults. |
defaults
defaults takes model, effort and permission_mode. Two refusals apply to any other key:
- Kraft refuses the file when it reads it if the provider does not declare the key, or does not accept the value.
- A key the provider declares but Kraft does not apply stops the task that selects the harness profile, and the task waits for you.
Which options each provider declares is listed in Agent harnesses and Harness definition files.
profiles: agent profiles
An agent profile names the model and effort a tier runs on, for each provider.
profiles:
strong:
providers:
claude: { model: sonnet, effort: high }
codex: { model: gpt-5.6-terra, effort: high }
| Field | Type | Default | Meaning |
|---|---|---|---|
<agent profile id> | string | required | The name a task's profile: selects: lowercase letters, digits, _ and -. |
providers | mapping | required, unless model is given | Maps a provider ID to {model, effort?}; a provider left out cannot run this agent profile. The shape the Harnesses screen writes. |
model, effort | mapping, string | none | The older shape, still read: one model map and one effort shared by every provider. An agent profile is written in one shape, never both. |
fallback | list | none | The tier's default fallback list for a task that sets none. |
Kraft refuses an agent profile that has neither providers nor the older model, and one where either is empty.
Inspect and edit
kraft admin harnesseslists every harness profile with its provider and the library tasks that select it, then each agent profile.kraft admin harnesses IDshows one harness profile.- Settings › Harnesses shows each harness with its access, its executable and defaults, and what its provider accepts, and each agent profile with one lane per provider.
- Settings › Harnesses edits one harness or agent profile at a time: a harness's access, executable and defaults, and an agent profile's provider entries (model and effort). It also renames, copies and removes an agent profile.
Kraft refuses a save that would stop an agent task of any chain that loads today from launching, and writes nothing. A save writes only what it changed: the file's comments and layout stay.
A harness's access
A harness's access is one of three values. It is set by where the harness is listed in the two allowed_harnesses lists of policy.yaml:
| Access | Where the harness is listed |
|---|---|
| Available | In defaults and maxima. |
| Override | Only in maxima; a task may use it only if its own policy: widens it. |
| Never | In neither. |
Related
- Agent profiles: how a task selects a tier and how it resolves per provider.
- Harness definition files: the files in
config/harnesses/that describe a harness itself, not a harness profile of it. - Switch a task to another harness: move one task from one harness profile to another.