Architecture
This page describes Keel’s architecture at the public product boundary. It is about runtime responsibilities, execution ownership, and evidence flow, not internal stage names or service wiring.
For the quick route chooser, use Overview. For public claims and non-claims, use Product Boundary.
An AI Permit is the pre-execution decision record Keel makes for a request submitted through a supported Keel decision surface. It may allow, deny, throttle or require review. Only
allowauthorizes execution.
Runtime layers
Keel’s public runtime is organized around five customer-visible layers:
- Ingress and project auth. Public runtime routes authenticate into a project and reject requests that cannot be scoped safely.
- Decision. Keel evaluates policy, budget, routing intent, and supported controls before execution work is allowed to proceed.
- Dispatch. On Keel-managed routes, Keel resolves project-scoped provider credentials and sends the provider request after the decision permits it.
- Reconciliation. Usage, cost, and terminal state are attached to the governed request after execution finishes or fails.
- Evidence. Permits, executions, usage, jobs, governance events, and timelines remain available through documented readback surfaces.
The route family determines which layers Keel owns. Permit-first owns the decision and evidence boundary while the caller owns provider transport. Keel-managed execution routes own decision, dispatch, reconciliation, and route-appropriate evidence.
Execution ownership
| Mode | Primary route | What you can rely on |
|---|---|---|
| Primary public runtime | POST /v1/execute | Provider-shaped input, resolved target metadata, normalized output |
| Provider-neutral execution contract | POST /v1/executions | One portable request contract, Keel-managed execution, normalized output |
| Provider-native proxy | POST /v1/proxy/* | Provider-native payloads and responses with Keel governance in front |
| Advanced permit-first integration | POST /v1/permits | Decision record now, provider execution in your app, caller-reported closeout later if required |
For the full mode comparison, use Execution Modes.
Evidence path
AI Permit issuance and supported managed-execution routes start with an AI Permit. Dry-run evaluation does not issue or persist one. Downstream records differ by route:
- permit-first integrations can attach usage closeout and verification material after the caller-owned provider request completes
- synchronous Keel-managed execution routes attach routing, provider response metadata, usage, timing, and terminal status to the request record
- async jobs persist job state separately while reusing the same governance and execution evidence path
- request timeline replay reconstructs the lifecycle from persisted records rather than from transient logs
For the event-level lifecycle, use Request Lifecycle and Execution Lifecycle.
Trust boundaries
The public runtime model has a few important boundaries:
- project is the primary tenancy boundary for public runtime requests
- Keel-managed routes use project-scoped provider credentials held server-side
- permit-first integrations keep provider credentials and provider transport in the caller’s application
- routing is explicit and recorded; it is not a claim of autonomous provider selection across every provider and route
- replay, content inspection, and integrity guarantees are route-specific
For exact commitments, use API Guarantees, Route Guarantees, and Scope and Limits.