Which Kestrel product should I start with?
Use Desktop for work in local folders and repositories. Use Kestrel One source for inspection and local development, or the invitation-only Lumi-hosted service for shared Threads, Projects, and Knowledge. Use the CLI/TUI for supported terminal work. Use the SDK or HTTP interfaces when Kestrel should run behind an application you own. The journey chooser compares the first steps.
Do I need to run a database for Desktop?
No. Kestrel Desktop includes Local Core and manages its own persistence. You choose a model provider and a project folder during first run.
Can anyone sign up for Kestrel One?
The Lumi-hosted service is available to invited teams. Use the invitation from your organization administrator to sign in or create the invited-email account, then explicitly join the organization. Kestrel One source remains available from the release tag; hosted signup and turnkey production self-hosting are separate questions.
How is Kestrel One downloadable if hosted access is invitation-only?
Kestrel One is a versioned source product. You may clone v0.8.5, build it, test it, and run its development environment. Lumi hosting is one operated deployment of that source and requires an organization invitation. See Source and hosting.
Which platforms does the 0.8 CLI support?
Release verification covers macOS arm64 and Linux x64 with Node.js 22. Install it with npm install -g @kestrel-agents/kestrel@0.8.8. Other platforms are not release-verified for 0.8.
Does installing Desktop 0.8 preserve existing data?
Yes. Replacing the signed application preserves Desktop and Local Core settings, Keychain credentials, projects, sessions, conversations, Mission Control records, and owned persistence. Do not uninstall or delete application data as part of the upgrade.
Can Desktop update from an earlier release?
Yes. Signed Desktop 0.7.0, 0.8.0, and 0.8.5 installations can update to 0.8.6 through the stable channel. Desktop preserves a one-time pre-v12 settings backup before migrating App and MCP settings; use that backup before launching an older application after a downgrade.
How do I match Kestrel package versions?
Use the versions in the compatibility matrix. Exact first-party dependency pins must match the owning package manifest because Runtime, Protocol, SDK, Memory, adapters, and clients exchange exact fields, events, terminal states, approvals, and recovery decisions. Runtime/CLI is 0.8.8 and its public dependencies are 0.8.5; independently released products such as Desktop can carry a different version. Kestrel does not promise 0.7/0.8 shims.
What are profiles and provider capabilities?
A Profile selects registered runtime policy. A Provider Registry entry identifies a provider/model path and qualified capabilities such as tool or structured-input support. A configured model is not ready until reachability, compatibility, qualification, authority, and budget checks pass.
What happens when Kestrel needs approval or recovery input?
Kestrel records a waiting request with registered options. Your response binds to the exact request and, for external effects, the exact proposed action. The original session or Thread continues after the decision.
How do I verify which hosted Kestrel revision is running?
Record the Vercel deployment and migration result and the operator-selected tag, provider record, and health result for each manually changed worker or tenant Environment. Do not infer hosted state from a semantic version or another target's result.
Why not call a model directly?
A direct call is simpler for a stateless answer. Kestrel becomes useful when work must continue across requests, wait for a person, produce artifacts, support operator intervention, or leave enough evidence to explain and replay later.
What is the runner service?
It is the network-hosted form of the Kestrel runtime. A trusted application server calls it with authenticated user and session context. It exposes the same Execution Protocol that Local Core provides locally, but through HTTP and streaming endpoints. A browser should not receive its bearer token or provider credentials.
For local development, kestrel web provides a compatible HTTP URL by bridging
requests to Local Core. It does not start a second runtime.
What is the difference between streaming and subscriptions?
Streaming follows the request you just started. A subscription follows selected background events for a session, Thread, or run. Replay examines persisted evidence after execution ends.
When should I use OpenAI-compatible HTTP instead of the SDK?
Use compatible HTTP when an existing server already speaks OpenAI-style chat or responses APIs. Use the SDK when you want typed agents, sessions, memory, streaming, waiting, resume, cancellation, and richer Kestrel controls.
When is Kestrel too much?
Kestrel may be unnecessary when a feature only sends a prompt and shows an answer, with no durable state, recovery, operator workflow, or later audit requirement.
How do I deploy it?
Run the runner service behind your application server, configure authenticated
server-to-server access, then verify the complete request and recovery path.
For local development, expose Local Core with kestrel web. Start with
Operate for the distinction between local and remote environments.