Python SDK · Kestrel Docs

Terminal

pip install kestrel

Kestrel

Python

Kestrel(api_key=None, default_repo=None, base_url=None, timeout_ms=60_000, max_retries=4)

AsyncKestrel takes the same options, and every method on it is awaitable.

runs

runs.create

Python

run = kestrel.runs.create(
    repo="acme/web-app",
    task="Fix the flaky checkout test",
    agent="claude-code",          # optional
    from_="web-app-seeded",       # optional snapshot; from is a keyword in Python
    routing={"floor": "medium"},  # optional
    evals={"repeat_tests": 20},   # optional
)

run.steps and run.wait

Python

for step in run.steps():
    print(step.name, step.duration_ms)

result = run.wait()
print(result.status, result.pull_request.url if result.pull_request else None)

Field	Type
`status`	`"pr_opened"`, `"needs_review"`, `"cancelled"` or `"failed"`
`pull_request`	`PullRequest(number, url)` or `None`
`gate`	Each check with its result and time
`usage`	`Usage(sandbox_minutes, tokens, cost_usd)`

runs.get, runs.list, runs.cancel, runs.trace

Python

kestrel.runs.get("run_8f2c")
kestrel.runs.list(repo="acme/web-app", status="queued", limit=20)
kestrel.runs.cancel("run_8f2c")
kestrel.runs.trace("run_8f2c")

sandboxes

Python

sandbox = kestrel.sandboxes.create(repo="acme/web-app", timeout_ms=600_000)
sandbox.commands.run("npm test")
sandbox.files.write("notes.md", "...")
sandbox.pause()
kestrel.sandboxes.resume(sandbox.id)
sandbox.snapshot(name="web-app-seeded")
sandbox.kill()

Async

Python

import asyncio
from kestrel import AsyncKestrel

async def main():
    kestrel = AsyncKestrel()
    runs = [await kestrel.runs.create(repo="acme/web-app", task=t) for t in tasks]
    results = await asyncio.gather(*(r.wait() for r in runs))

asyncio.run(main())

Errors

Errors raise kestrel.KestrelError, with subclasses AuthError, ForbiddenError, RateLimitedError (with retry_after), NotFoundError and ServerError.