# TypeScript SDK

Every method in @kestrel/sdk, with its options and what it returns. Works in Node 18 and later, Bun and Deno.

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

## Kestrel

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

See [SDK client](/sdk-client) for each option.

## runs

### runs.create

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

```ts 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.

```ts 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

```ts 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

```ts 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](/sandbox/lifecycle) and [Files](/sandbox/files).

## memory

```ts 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](/runs/rate-limits) 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 |