Kestrel is an open runtime platform for agent work that cannot be reduced to a single request and response. It gives every run an identity, terminal outcome, event history, artifacts, and operator controls so work can survive interruptions without becoming a black box.

Use Kestrel through a packaged desktop application, the hosted Kestrel One product, a CLI/TUI, or typed server-side packages. Every surface shares the same execution and result contracts.

Release status: this repository and its documentation describe the 0.6.0-beta.0 contract line. Package and product availability may be staged. Check 0.6 Beta release status before distributing an installer or pinning a production dependency.

Read the docs · Choose a quickstart · Understand the architecture · Contribute

Why Kestrel

A direct model call is enough for a disposable answer. Production agent work usually needs more:

• Continuity: sessions and runs persist beyond one browser request or process lifetime.
• Control: people can inspect, steer, stop, resume, retry, and approve work without creating an unrelated conversation.
• Durable outcomes: completed, failed, cancelled, and waiting states are explicit rather than inferred from the last message.
• Evidence: events, artifacts, checkpoints, and operator decisions remain available for diagnosis, replay, and evaluation.
• Governed effects: filesystem, shell, network, model, and MCP capabilities cross typed and policy-aware tool boundaries.
• Application contracts: human-facing assistantText stays separate from structured finalizedPayload data.

The result is agent work that can be operated as a system—not merely watched as a chat transcript.

Choose Your Path

| Goal | Start here | What you get | | --- | --- | --- | | Run agents against local files and repositories | Kestrel Desktop | A packaged macOS application with local workspaces, persistent sessions, recovery, and operator control | | Continue agent work with a team | Kestrel One | Shared Threads, Projects, Knowledge, artifacts, access control, and managed model access | | Add durable agents to an application | Build your first agent | Typed TypeScript SDK, runner protocol, Next.js helpers, AI SDK adapter, and observability | | Operate or troubleshoot a deployment | Operations | Reliability, security, replay, evaluation, deployment, and incident workflows | | Work from the terminal | CLI and TUI | Local Core commands, interactive sessions, durable jobs, evidence, and automation |

How It Fits Together

flowchart LR
    U["Person or product"] --> S["Desktop, Kestrel One, CLI, or app server"]
    S --> R["Authenticated runner boundary"]
    R --> K["Durable Kestrel runtime"]
    K --> M["Model providers"]
    K --> T["Allowed tools and MCP services"]
    K --> E["Events, results, artifacts, and checkpoints"]
    E --> S

Credentials and trusted identity stay on controlled clients or application servers. The runtime owns execution state and effects. Product surfaces own their user experience; they do not reconstruct a second runtime.

Read Kestrel Architecture for authority, data flow, and package boundaries.

Build With Kestrel

The application-facing SDK talks to an explicit Local Core or remote runner target. It does not run agents in the browser or infer execution authority from ambient process state.

pnpm add @kestrel-agents/[email protected]

import { createAgent } from "@kestrel-agents/sdk";

const agent = createAgent({
  id: "support-agent",
  profileId: "support",
  target: {
    kind: "remote",
    baseUrl: process.env.KESTREL_RUNNER_SERVICE_URL!,
    authToken: process.env.KESTREL_RUNNER_SERVICE_TOKEN!,
  },
});

const terminal = await agent.run(
  {
    sessionId: "customer-42",
    message: "Investigate the failed deployment and prepare a recovery plan.",
  },
  {
    actor: { actorId: "user-42", actorType: "end_user" },
    tenantId: "acme",
  },
);

console.log(terminal.payload.result.assistantText);
console.log(terminal.payload.result.finalizedPayload);

Go deeper with the SDK guide, Next.js helpers, AI SDK adapter, and observability package.

Run the Repository Locally

Kestrel uses Node.js 22 in CI and pnpm 9. No provider credentials are required to install dependencies or run the offline validation suites.

git clone https://github.com/LumiCorp/kestrel.git
cd kestrel
corepack enable
pnpm install

Start the surface you are working on:

pnpm run desktop:dev  # packaged local product
pnpm run web:dev      # Kestrel One
pnpm run docs:dev     # documentation site
pnpm run tui          # terminal interface

Model-backed development requires a configured provider. Start from .env.example; Kestrel One has additional settings in apps/web/.env.example.

Repository Map

| Path | Responsibility | | --- | --- | | src/ | Runtime contracts, execution, orchestration, persistence, replay, Local Core, and shared adapters | | cli/ | kestrel, ks, kcron, TUI, and runner-service commands | | apps/desktop/ | Electron desktop application over Local Core | | apps/web/ | Kestrel One hosted product | | apps/docs/ | Public Next.js/MDX documentation site | | packages/ | Protocol, SDK, Next.js, AI SDK, and observability packages | | agents/reference-react/ | Canonical reference agent | | tools/ | Typed tool contracts, catalog, and handlers | | evals/ | Declarative evaluation scenarios and release ownership evidence | | docs/ | ADRs, plans, runbooks, references, analysis, and maintainer evidence |

Quality Gates

Run a focused test while iterating. Before a runtime or repository-wide change is considered ready, run the shared gates:

pnpm run governance:check
pnpm run test
pnpm run prompt-suite
pnpm run evals:release-check

These gates protect architecture boundaries, public contracts, deterministic replay, model-visible behavior, package compatibility, and declarative Ruhroh evaluation inputs. See Reliability for the verification and incident model.

Project Boundaries

• Kestrel owns the open runtime, Local Core, CLI/TUI, Desktop, Kestrel One, public packages, tools, and declarative evaluation specifications in this repository.
• Ruhroh is a separate evaluation project. It owns evaluation execution, reports, comparison, and the maintained Kestrel adapter; this repository owns the specifications under evals/.

Documentation

• Documentation map
• Architecture
• Design principles
• Reliability
• Security
• Quality score
• Contributing
• Support

Contributing and Support

Contributions are welcome. Read CONTRIBUTING.md for setup, change ownership, and validation expectations.

Use GitHub Issues for reproducible bugs and feature requests. Do not report vulnerabilities publicly; follow the private disclosure process in SECURITY.md.

Kestrel is available under the MIT License.