TypeScript SDK · Kestrel Docs

Terminal

npm i @kestrel/sdk

Kestrel

TypeScript

new Kestrel(options?: { apiKey?: string; defaultRepo?: string; baseUrl?: string; timeoutMs?: number; maxRetries?: number })

See SDK client for each option.

runs

runs.create

Start a run. Returns as soon as the run is queued.

TypeScript

const run = await kestrel.runs.create({
  repo: "acme/web-app",          // required unless defaultRepo is set
  task: "Fix the flaky checkout test",
  agent: "claude-code",          // optional, see Connect your agent
  from: "web-app-seeded",        // optional snapshot
  routing: { floor: "medium" },  // optional
  evals: { repeatTests: 20 },    // optional
});

Returns a Run: { id, repo, task, status, createdAt }.

run.steps

An async iterator of steps as they finish.

TypeScript

for await (const step of run.steps()) console.log(step.name, step.durationMs);

run.wait

Wait for the run to end. Returns a RunResult.

Field	Type
`status`	`"pr_opened"`, `"needs_review"`, `"cancelled"` or `"failed"`
`pullRequest`	`{ number, url }` when a pull request opened
`gate`	Each check with its result and time
`usage`	`{ sandboxMinutes, tokens, costUsd }`

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

TypeScript

await kestrel.runs.get("run_8f2c");
await kestrel.runs.list({ repo: "acme/web-app", status: "queued", limit: 20 });
await kestrel.runs.cancel("run_8f2c");
await kestrel.runs.trace("run_8f2c");

sandboxes

TypeScript

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

See Sandbox lifecycle and Files.

memory

TypeScript

await kestrel.memory.list("acme/web-app");
await kestrel.memory.add("acme/web-app", { topic: "tests", text: "Run with --runInBand" });
await kestrel.memory.forget("acme/web-app", { topic: "tests" });

Errors

Every error is a KestrelError with a type you can switch on.

`type`	When
`auth`	The key is missing, wrong or revoked
`forbidden`	The key can't see that repo
`rate_limited`	A rate limit was reached; `retryAfter` says when to try again
`not_found`	No run or sandbox with that id
`server`	Something failed on our side; the SDK has already retried