Running your first task

1. Create a Kestrel account

   Every new workspace starts on Hobby: 100 runs a month on one repo, free. Open the dashboard and connect GitHub when it asks.

2. 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.
   .env

   KESTREL_API_KEY=kst_live_••••••••

3. Install the SDK

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

   TypeScriptPython

   npm i @kestrel/sdk

4. 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.

   TypeScriptPython

   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}`);

5. Watch it work

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

   TypeScriptPython

   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"

6. Or do it all from the terminal

   The CLI does the same in two commands.

   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

Next steps

• Connect your agent to run Claude Code, Codex or your own loop.
• Allow a network host if your build installs packages.
• Read a run's trace to see where the time went.