Architecture overview

Kestrel has one execution architecture with two deployment forms. Desktop, CLI/TUI, Kestrel One, and SDK applications provide different experiences, but they share the same contracts for runs, events, tools, persistence, recovery, and terminal results.

Local and remote deployments

local
  Desktop, CLI/TUI, or a local SDK target
    -> Local Core
      -> Execution Protocol
        -> Kestrel runtime
 
remote
  Kestrel One or a remote SDK target
    -> runner service
      -> Execution Protocol
        -> Kestrel runtime

Local Core is the runtime host on a user's computer. It manages local configuration, credentials, persistence, and an authenticated Unix socket. Desktop starts or reconnects to Local Core automatically.

A runner service is the network-hosted form. Trusted application servers reach it through authenticated HTTP and streaming endpoints. Browser code calls the application server and never receives runner or provider credentials.

Both hosts expose the same Execution Protocol and use the same runtime implementation. They are different deployments, not different execution systems.

The durable runtime

The runtime coordinates run and step lifecycle, model and tool input/output, persistence, waiting, cancellation, events, artifacts, and replay evidence. It does not need to know which user interface initiated the request.

Every run ends with an explicit completed, failed, cancelled, or waiting outcome. Live streams follow individual requests, while persisted events make later subscription, diagnosis, and replay possible.

Product and integration surfaces

• Desktop provides the packaged local experience over Local Core.
• The CLI and TUI provide local workflows and operator controls over Local Core.
• Kestrel One sends authenticated organization and user work to remote runner targets.
• The SDK supports explicit local and remote execution targets.
• Next.js and AI SDK helpers adapt the SDK for application routes and UI messages.

For local application development, kestrel web exposes Local Core through an authenticated loopback HTTP bridge. It does not start another runtime.

Read Core concepts for the shared vocabulary or Running the runner service for local and remote connection models.