Kestrel is easiest to understand by following both the request path and the evidence path. The request path starts work. The evidence path is what lets a person or application inspect, continue, recover, and trust that work later.
Request path
- A person, CLI, or application starts from Desktop, Kestrel One, the TUI, SDK, Next.js route, or compatible HTTP endpoint.
- The owning application resolves actor, tenant or organization, project/workspace, session/thread, and correlation.
- It sends validated input to Local Core or a remote runner.
- The runner resolves the effective profile, provider/model, tools, memory, budgets, and policy.
- The runtime advances the turn and records a terminal or waiting outcome.
Browsers never own runner credentials, provider secrets, external approvals, or trusted execution policy.
Execution path
The runtime validates input before use, assembles context, calls the model through the provider boundary, validates tool calls, executes allowed effects through their owners, and commits visible output only when the corresponding state is durable. A run may complete, fail, cancel, or wait for an exact human decision.
Profile and provider selection
The canonical kestrel profile defines the shipped runtime behavior. A versioned provider registry supplies approved provider/model identities and capability evidence. Configured, reachable, compatible, qualified, and authorized are separate readiness checks.
Streaming, subscriptions, and replay
Streaming provides live events while a request is connected. Subscriptions continue to deliver durable activity after the initiating request ends. Cursors let consumers reconnect without guessing where history stopped. Replay reconstructs recorded decisions and results; it does not silently repeat uncertain external effects.
Memory and continuity
Session history carries the conversation. Governed runtime memory adds authorized durable facts with subject, issuer, provenance, and query policy. Kestrel One Knowledge supplies organization or Project material through revisioned context. These systems can cooperate without becoming interchangeable stores.
Mission Control and control-plane state
Mission Control owns project work, attempts, evidence, review, and acceptance. Runtime operator control owns a running or waiting conversation. Keep project authority, execution authority, review authority, and migration authority distinct.
Recovery, approvals, and budgets
Recovery offers registered actions bound to the observed state. External approvals bind an authorized grant to one exact action/effect. Budgets reserve and commit governed spend through a durable ledger. None of these decisions should be inferred from free-form text.
Observability and evaluation
Trace context connects request, session/thread, run, turn, tool/effect, provider, and terminal result. Provider-returned reasoning and agent-authored progress remain distinct. Runtime evaluation records policy, evidence, and delivery outcomes without rewriting the primary result.
Workspaces and Environments
A local workspace is the owned folder or checkout where Desktop or CLI work occurs. A Kestrel One Environment is the hosted compute and capability boundary that supplies Projects with runtime images, workspaces, Apps, MCP, network policy, credentials, and activity.
Deployment and release identity
Every surface has a product version. A deployed system also needs an exact source revision, migration state, application deployment, worker revision, and immutable image digest. Version alone does not prove what code is running.
Decisions an integrator must make
Choose the trusted application boundary, execution target, actor and tenant model, profile/provider policy, persistence, memory authority, tools and approvals, budget ownership, event consumption, observability, and release process.
Next steps
Continue with Core concepts, Build your first agent, or Operate a runner service.