Kestrel Documentation

What is Kestrel?

Kestrel is a runtime for coding agents. You give it a repo and a task. It starts a sandbox with a copy of the repo, runs your agent inside it, checks the diff against your tests and our evals, and opens a pull request when every check passes.

Install the SDK:

npm i @kestrel/sdk

pip install kestrel

Then start a run:

import { Kestrel } from "@kestrel/sdk";

const kestrel = new Kestrel(); // reads KESTREL_API_KEY
const run = await kestrel.runs.create({
  repo: "acme/web-app",
  task: "Fix the flaky checkout test",
});
const result = await run.wait();
console.log(result.pullRequest?.url);

from kestrel import Kestrel

kestrel = Kestrel()  # reads KESTREL_API_KEY
run = kestrel.runs.create(
    repo="acme/web-app",
    task="Fix the flaky checkout test",
)
result = run.wait()
print(result.pull_request.url)

Kestrel building blocks

The four parts you will work with:

• Sandbox: a sealed Linux VM made for one task. The repo goes in, only the diff comes out, and the sandbox is wiped when the task ends.
• Memory: what an agent works out about your repo, kept between runs, so the next run starts where the last one stopped.
• Eval gate: your tests and our evals, run in order on every diff. A failing diff goes back to the agent with the failure attached.
• Traces: every file read, tool call and test in a run, on one time axis.

How to use the docs

• Quickstart: your first run, step by step, in about five minutes.
• Guides: longer walkthroughs for one job, like fixing flaky tests or running Kestrel from an issue label.
• SDK Reference: every method in the TypeScript and Python SDKs, and every CLI command.

Quickstart

Guides