# Kestrel Documentation

Kestrel runs your coding agents in sealed sandboxes, keeps what they learn about your repo, and opens a pull request only when the evals pass. Start a run from the SDK in a few lines.

## 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:

```bash TypeScript
npm i @kestrel/sdk
```

```bash Python
pip install kestrel
```

Then start a run:

```ts TypeScript
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);
```

```python Python
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)
```

![One run from start to finish: the task leaves the queue for a sandbox, the agent reads the repo and writes a diff, every test passes, and only then does a pull request open and merge.](/illos/agent-run.svg)

## Kestrel building blocks

The four parts you will work with:

- [Sandbox](/sandbox/lifecycle): 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](/agents/memory): what an agent works out about your repo, kept between runs, so the next run starts where the last one stopped.
- [Eval gate](/review/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](/runs/traces): every file read, tool call and test in a run, on one time axis.

## How to use the docs

- [Quickstart](/quickstart): your first run, step by step, in about five minutes.
- [Guides](/guides/flaky-tests): longer walkthroughs for one job, like fixing flaky tests or running Kestrel from an issue label.
- [SDK Reference](/sdk/typescript): every method in the TypeScript and Python SDKs, and every CLI command.

> [!NOTE]
> Working with your own coding agent? These docs are written for agents too. Every page is served as Markdown at the same address with `.md` on the end, and [`/llms.txt`](/llms.txt) lists them all.

## Quickstart

- [Run your first task](/quickstart): Start a run from the CLI or the SDK and get a pull request back.
- [Connect your agent](/agents/connect): Bring Claude Code, Codex or your own agent loop, and give it Kestrel's tools.
- [Move files in and out](/sandbox/files): Upload fixtures to a sandbox and download what the agent made.
- [Allow a network host](/sandbox/network): Keep outbound traffic off, and open only the registries a build needs.

## Guides

- [Fix flaky tests](/guides/flaky-tests): Point Kestrel at a test that fails one run in ten and get a fix with proof.
- [Run from a GitHub issue](/guides/github-issues): Label an issue and Kestrel opens a pull request for it.