Getting started

This guide walks you from zero to your first captured event in under five minutes.

1. Run Kestrel

The fastest path is the official Docker image. It's scratch-based, multi-arch (amd64 + arm64), and ~13 MB.

docker run -d \
  --name kestrel \
  -p 8080:8080 \
  -v kestrel-data:/data \
  ghcr.io/wearzdk/kestrel:latest

On the first start Kestrel generates a temporary admin password, prints it to the container logs, and writes it to /data/.admin_password. Either grab it from docker logs kestrel or set one yourself with -e KESTREL_ADMIN_PASSWORD=....

If you'd rather run a static binary, grab one from the latest release — it's a single executable for Linux, macOS, or Windows. No runtime dependencies.

2. Log in and create a project

Open http://localhost:8080. Log in with the admin password from step 1. Create a project — give it any name — and copy the ingest token shown in the one-shot modal. Save it now — Kestrel only stores a hash, so the token is never displayed again. (You can rotate it anytime from the Settings page if you lose it.)

3. Send your first event

Pick the SDK that matches your stack:

JavaScript

npm install kestrel-sdk

Python

pip install kestrel-sdk

Go

go get github.com/wearzdk/kestrel/sdks/go@latest

Then wire it up at process start:

JavaScript

import { init } from 'kestrel-sdk'

init({
  endpoint: 'http://localhost:8080/api/v1/ingest',
  token: 'YOUR_PROJECT_TOKEN',
})
// `window.error` and `unhandledrejection` are now captured automatically.

Python

import kestrel_sdk
kestrel_sdk.init(
    endpoint="http://localhost:8080/api/v1/ingest",
    token="YOUR_PROJECT_TOKEN",
)
# sys.excepthook is wired up.

Go

import kestrel "github.com/wearzdk/kestrel/sdks/go"

if err := kestrel.Init(
    "http://localhost:8080",
    "YOUR_PROJECT_TOKEN",
); err != nil {
    panic(err)
}
defer kestrel.Recover(ctx) // captures panics

Trigger an exception in your code. Within a second a fresh issue appears in the Kestrel web UI.

4. Hand the keys to an AI

Kestrel's headline feature is the built-in MCP server. Add it to Claude Code (or any MCP-aware client) so the agent can read errors itself. The HTTP transport works for both Docker and binary installs:

// ~/.claude/mcp.json
{
  "mcpServers": {
    "kestrel": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer YOUR_PROJECT_TOKEN" }
    }
  }
}

Now the agent has tools called list_errors, get_error, mark_resolved, mark_ignored, and get_trend — see the MCP overview for the full reference (including the local stdio transport).

Where to next

• Self-hosting — Docker recipes, configuration, reverse-proxy snippets, TLS.
• Backups — kestrel backup and the restore flow.
• Metrics & health — /metrics, /healthz, /healthz/ready.
• SDK reference — what each SDK actually captures and how to manually push extra events.