# Kestrel Docs

> Docs for Kestrel, the runtime for coding agents: sealed sandboxes, repo memory and an eval gate before every pull request. Every page is also served as Markdown.

## Docs: Getting started

- [Kestrel Documentation](/index.md): 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.
- [Running your first task](/quickstart.md): This guide starts your first Kestrel run, from an API key to a pull request, in about five minutes.
- [API key](/api-key.md): Every request to Kestrel carries an API key. Keys belong to a workspace, can be limited to some repos, and can be rotated without downtime.
- [SDK client](/sdk-client.md): The Kestrel client holds your key, your defaults and its retry rules. Make one per process and share it.
- [Billing & limits](/billing.md): Kestrel bills for runs, not for seats nobody uses. Usage is metered in sandbox minutes and model tokens, and settled once a month.

## Docs: Sandbox

- [Sandbox lifecycle](/sandbox/lifecycle.md): The sandbox lifecycle: create one for a task, run commands in it, pause it to keep its state, and kill it when the work is done. Runs do all of this for you; the SDK lets you do it yourself.
- [Persistence & snapshots](/sandbox/persistence.md): Pause a sandbox to keep its disk and memory, resume it later exactly where it was, or take a snapshot to start new sandboxes from the same state.
- [Network egress](/sandbox/network.md): Sandboxes have no outbound network by default. Allow the hosts a build needs by name; every other name never resolves, so nothing else can leave.
- [Files](/sandbox/files.md): Write files into a sandbox before a run, read what the agent made, and move large files in parallel chunks.

## Docs: Agents

- [Connect your agent](/agents/connect.md): Kestrel runs the agent you already use. It gives that agent a set of tools inside the sandbox and records every call they make.
- [Agent memory](/agents/memory.md): What an agent works out about your repo settles into memory that outlasts the run. The next run starts where the last one stopped, not from zero.
- [Context window](/agents/context.md): Long runs fill an agent's context. Kestrel compacts old turns into a summary instead of cutting them off, so the agent keeps working with room to spare.
- [Model routing](/agents/routing.md): Kestrel scores each step before it runs and sends it to the smallest model that can do it. Renames go to a small model; only the hard reasoning reaches a large one.

## Docs: Runs

- [Queue & concurrency](/runs/queue.md): Runs wait in one queue per workspace and start in the order they came in, as workers free up. Nothing is dropped and nothing jumps the line.
- [Run traces](/runs/traces.md): Each run records its steps as a trace: every file read, every tool call and every test, on one time axis. The slow step is obvious at a glance.
- [Rate limits](/runs/rate-limits.md): Set how fast each repo may start runs and spend. Bursts above the limit are turned away at the edge, before they cost anything.
- [Retries](/runs/retries.md): Network errors and busy models are retried with growing waits between tries. A run is never started twice, because each request carries an idempotency key.

## Docs: Review

- [Eval gate](/review/eval-gate.md): Every diff runs your tests and our evals, in order, before a pull request opens. A failing diff goes back to the agent with the failure attached.
- [Pull requests](/review/pull-requests.md): When a diff passes the eval gate, Kestrel opens a pull request on a branch of its own, with what it did, why, and the proof that the checks passed.

## Guides: Guides

- [Fix flaky tests](/guides/flaky-tests.md): Point Kestrel at a test that fails one run in ten. It finds why, fixes it, and proves the fix by running the test until a failure would have shown.
- [Run from a GitHub issue](/guides/github-issues.md): Label an issue with kestrel and Kestrel picks it up, works on it, and links the pull request back to the issue.

## SDK Reference: SDKs

- [TypeScript SDK](/sdk/typescript.md): Every method in @kestrel/sdk, with its options and what it returns. Works in Node 18 and later, Bun and Deno.
- [Python SDK](/sdk/python.md): Every method in the kestrel package, with its options and what it returns. Python 3.9 and later, sync and async.
- [CLI](/sdk/cli.md): The kestrel command: set up a repo, start runs, read traces and edit memory from the terminal.

## API Reference: REST API

- [REST API](/api/overview.md): The SDKs wrap a plain JSON API. Use it from any language, or from curl.
- [Runs](/api/runs.md): Start a run, follow it, and read its trace.
- [Sandboxes](/api/sandboxes.md): Make and manage sandboxes outside a run.

## Changelog: Changelog

- [Changelog](/changelog.md): What changed in Kestrel, newest first.

## FAQ: FAQ

- [Frequently asked questions](/faq.md): Short answers to what people ask before their first run.