# Running your first task

This guide starts your first Kestrel run, from an API key to a pull request, in about five minutes.

### Create a Kestrel account

Every new workspace starts on Hobby: 100 runs a month on one repo, free. [Open the dashboard](https://kestrel-black-seven.vercel.app/?utm_source=kestrel-docs) and connect GitHub when it asks.

### Set your API key

1. Open **Settings → API keys** in the dashboard.
2. Create a key and copy it. You will see it once.
3. Paste it into your `.env` file.

```dotenv .env
KESTREL_API_KEY=kst_live_••••••••
```

### Install the SDK

Install the SDK in your project, or use the CLI with `npx` and skip this step.

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

```bash Python
pip install kestrel
```

### Start a run

Give Kestrel a repo and a task in plain words. It starts a sandbox, copies the repo in, and hands the task to your agent.

```ts TypeScript {4-7}
import { Kestrel } from "@kestrel/sdk";

const kestrel = new Kestrel();
const run = await kestrel.runs.create({
  repo: "acme/web-app",
  task: "Fix the flaky checkout test",
});
console.log(`Watching ${run.id}`);
```

```python Python {4-7}
from kestrel import Kestrel

kestrel = Kestrel()
run = kestrel.runs.create(
    repo="acme/web-app",
    task="Fix the flaky checkout test",
)
print(f"Watching {run.id}")
```

### Watch it work

Each step arrives as it finishes. When the evals pass, the run ends with a pull request.

```ts TypeScript
for await (const step of run.steps()) {
  console.log(step.name, step.model, `${step.durationMs} ms`);
}
const result = await run.wait();
console.log(result.status, result.pullRequest?.url); // "pr_opened", ".../pull/412"
```

```python Python
for step in run.steps():
    print(step.name, step.model, f"{step.duration_ms} ms")
result = run.wait()
print(result.status, result.pull_request.url)  # "pr_opened", ".../pull/412"
```

### Or do it all from the terminal

The CLI does the same in two commands.

```bash Terminal
npx kestrel init
kestrel run "fix the flaky checkout test"

✓ sandbox ready              0.8 s
✓ 48 of 48 checks passed
✓ pull request #412 opened
```


> [!TIP]
> A run that cannot pass the evals after three tries stops with the status `needs_review` and no pull request. Its trace shows the failure the agent could not fix. See [Eval gate](/review/eval-gate).

## Next steps

- [Connect your agent](/agents/connect) to run Claude Code, Codex or your own loop.
- [Allow a network host](/sandbox/network) if your build installs packages.
- [Read a run's trace](/runs/traces) to see where the time went.