API key · Kestrel Docs

Create a key

Open Settings → API keys in the dashboard and choose Create key. Name it after where it will live, like ci or laptop, so you know which one to revoke later.

Keys start with kst_live_. Test keys start with kst_test_: they run in sandboxes that never open pull requests, which is handy in CI for the SDK itself.

Use it

The SDKs and the CLI read KESTREL_API_KEY from the environment. Pass it yourself when you need more than one workspace in a process.

const kestrel = new Kestrel({ apiKey: process.env.KESTREL_CI_KEY });

kestrel = Kestrel(api_key=os.environ["KESTREL_CI_KEY"])

For the REST API, send it as a bearer token:

Terminal

curl https://api.kestrel.dev/v1/runs \
  -H "Authorization: Bearer $KESTREL_API_KEY"

Limit a key to some repos

A key can see every repo in the workspace, or only the ones you pick. A key limited to acme/web-app gets a 403 for any other repo, so a leaked CI key cannot start runs elsewhere.

Scope	Can do
`runs:write`	Start, cancel and retry runs
`runs:read`	Read runs, steps and traces
`sandboxes:write`	Create, pause and kill sandboxes
`memory:write`	Edit and clear repo memory

Rotate a key

Create the new key, deploy it, then revoke the old one. Both work in the meantime, so nothing fails while the change rolls out.

Warning

Revoking a key stops runs it started at their next step. Runs already past the eval gate still open their pull requests.