Add or override a harness

Add a new agent CLI to Kraft, or change how a shipped one is launched, by dropping a YAML file into a directory. No Python change and no Kraft release are involved. For what each field means, see Agent harnesses.

Add a harness

1. Create $KRAFT_HOME/templates/harnesses/mytool.yaml (~/.kraft/templates/harnesses/ by default). Make the directory if it doesn't exist. The file name's stem must equal the id.
2. Start with the three required capabilities:

   id: mytool          # must match the file name's stem
   kind: cli           # the only kind implemented
   command: [mytool]   # argv prefix
   capabilities:
     prompt:  { cli: ["-p", "{value}"] }
     context: { channel: prompt }       # or: { channel: system_prompt, cli: [...] }
     usage:   { source: result_file }   # or: { source: envelope, reader: <parser name> }
   

3. Add each optional capability the CLI supports (model, effort, permission_mode, and so on) with the cli: fragment that sets it. Leave out what the CLI can't do. A task that asks for a capability you left out is rejected at load, pointing at this file.
4. Add a profile for the harness in ~/.kraft/templates/harnesses.yaml, then select it from a task. The profile's provider is your harness id:

   harnesses:
     mytool:
       provider: mytool
       enabled: true
       executable: mytool
   

   
   In library.yaml, a task that should run on it sets harness: mytool. See the harnesses file for every profile field.
5. Reload the templates so a running server rereads them:

   kraft admin reload
   

Verify

Run the install check:

kraft admin doctor

Expect a PATH row for your harness once a chain selects it, and no load error for your file. A load error names the file and the field to fix. To see which library tasks select each harness profile, run kraft admin harnesses.

Override a shipped harness

Use the same steps, with a file named after a shipped harness: claude.yaml, codex.yaml, cursor.yaml, opencode.yaml, gemini.yaml, or amp.yaml. Your file replaces the shipped one whole, so start from the shipped definition, src/kraft/harnesses/claude.yaml (one file per harness), and change only what you need, such as claude's --model allowlist.

Verify with kraft admin doctor, as above.

Set up Amp or Cursor credentials

A worker has no one to answer a login prompt, so give each CLI credentials it can use without one.

Both CLIs are covered in more detail in Agent harnesses. The steps here are the short path.

Amp

1. On a machine where you ran amp login, do nothing more. The login lives under your home directory, which a worker keeps. A sandboxed repository never sees it: its workers get a home of their own, so use steps 2-4.
2. Elsewhere, create an access token (sgamp_...) at ampcode.com/settings.
3. Name AMP_API_KEY in the repo's env_passthrough, because a worker's environment is an allowlist:

   # repos.yaml
   repos:
     - path: /path/to/repo
       env_passthrough: [AMP_API_KEY]
   

4. Export AMP_API_KEY in the shell that starts the Kraft server, then restart the server.

Cursor

1. On a machine where you ran agent login, do nothing more. The login lives in the OS keychain, which a sandboxed worker cannot reach.
2. With an API key instead (the only way under a sandbox), name CURSOR_API_KEY in the repo's env_passthrough, export it in the shell that starts the server, and restart the server.

Verify

File a small work item with a task on the harness, or run the CLI's own headless command by hand as the same user. Without credentials, Amp prints a device-login prompt and waits about five minutes for a browser before it exits 1, so a hang on that prompt means the credentials didn't reach the worker.