Skip to main content
Version: Latest

Architecture Decision Records

kora records every significant technical decision as an ADR. This index is the catalogue.

Naming. ADR files are named YYYY-MM-DD-kebab-slug.md — the decision date plus a short slug. There is no sequential number; the slug is the citation handle (e.g. inference-gateway-architecture). Files sort chronologically. The original sequential numbers are preserved in the Former # column below for traceability with older commits and discussions. To add one, copy template.md and follow the contributing workflow.

Status values: Proposed (under discussion) · Accepted (ratified; may or may not be fully implemented) · Deprecated / Superseded.

By subsystem​

Foundations & Platform​

Identity, Auth & Tokens​

Policy & Authorization​

Inference Gateway​

Agents Control Plane & Execution​

MCP / Tool Gateway​

Build order: Registration is the foundation; the Gateway depends on it, and on OAuth (which can be built in parallel with the Gateway).

Service Mesh, Operator & Deployment​

Frontend & Design System​

All ADRs (chronological)​

DateDecisionStatusFormer #
2026-02-16Language and Framework Selection (Go & Next.js)Accepted0002
2026-02-16Monorepo Technology StackAccepted0001
2026-02-17Controller-Based HTTP Routing with Stdlib ServeMuxAccepted0005
2026-02-17OTEL-Compatible Dependency-Injected LoggingAccepted0004
2026-02-17Repository Pattern and Code OrganizationAccepted0003
2026-02-18YAML File-Based Configuration with Typed Generic LoaderAccepted (Amended 2026-10-06)0006
2026-03-03Database Infrastructure LayerAccepted0007
2026-03-05Agent Execution Flow Patterns & DelegationAccepted0009
2026-03-05Credential-Aware Outbound GatewaySuperseded0012
2026-03-05MCP Server Registration, Deployment, and GovernanceAccepted0013
2026-03-05Scope-Gated Tool Exposure via MCPAccepted0014
2026-03-05Service Mesh and Network Enforcement InfrastructureAccepted0015
2026-03-05SPIFFE/SPIRE Workload AttestationAccepted0010
2026-03-05Unified Identity ModelAccepted0008
2026-03-05Universal Gateway as Policy Enforcement PointAccepted0011
2026-03-10Local Development EnvironmentSuperseded0016
2026-03-16OIDC Provider Abstraction and Local Identity ProviderAccepted0017
2026-03-17Dynamic SPIFFE Identity Grants and Tenant IsolationAccepted0018
2026-03-17Frontend Scaffolding and ToolchainAccepted0019
2026-03-19Multi-Service Backend Deployment StructureAccepted0020
2026-03-21Envoy ext_proc Sidecar for Transparent Platform Token InjectionAccepted0021
2026-03-21OpenTelemetry Observability DisciplineAccepted0022
2026-03-25Hades Frontend Design SystemAccepted0021
2026-03-31Helm Chart Distribution and GitOps Repository StructureAccepted0027
2026-03-31OIDC Client Secret Projection for Confidential TenantsAccepted0029
2026-03-31kora Kubernetes OperatorSuperseded0028
2026-03-31Tenant Registration and OIDC Provider BindingAccepted0026
2026-04-01Anthropic Zero-Translation PathAccepted (Amended 2026-10-07)0025
2026-04-01Browser-Based Authentication Flow and BFF Session ArchitectureAccepted0030
2026-04-01Home Realm Discovery and Email-Based Tenant RoutingAccepted0031
2026-04-01Inference Gateway ArchitectureAccepted0023
2026-04-01Model Capability TaxonomyAccepted (Amended 2026-10-10)0032
2026-04-01Provider Model Catalog and Alias RoutingAccepted (Amended 2025-07-22)0024
2026-04-02Personal Access Tokens for InferenceAccepted0033
2026-04-06Frontend Cluster Deployment and Ingress RoutingAccepted0034
2026-04-14Dynamic Route-Scope RegistrationAccepted (Amended 2026-10-01)0036
2026-04-14Frontend Policy Projection via BFFAccepted0037
2026-04-14Policy Gateway and Authorisation ModelAccepted (revised 2026-04-13)0035
2026-04-15Policy Administration DashboardAccepted (Amended 2026-10-22)0038
2026-04-17Inference Usage LogsAccepted0040
2026-04-17Virtual Model Catalog and Platform RoutingAccepted0039
2026-04-19PAT Scope Assignment via Explicit GrantsAccepted0041
2026-04-19User Profiles Table for Principal AttributionAccepted0042
2026-04-27Gateway-Level OPA Enforcement for External TrafficAccepted0044
2026-04-27Inference Analytics: My Usage and Analytics TabsAccepted (Amended 2026-07-20)0043
2026-05-03Embeddings and Responses API EndpointsAccepted0045
2026-05-04Frontend Component ConsolidationAccepted0046
2026-05-04Semantic HTML Consolidation — Unconditional Ban on header, article, nav, aside, footerAccepted0048
2026-05-04Hades Design System HardeningAccepted0047
2026-05-08Frontend Test Strategy and ToolchainAccepted0049
2026-05-11Agent CLI Framework & Transform LayerAccepted0049
2026-05-11Agent Event Streaming ProtocolAccepted0054
2026-05-11Agent Execution InfrastructureAccepted (Amended 2026-10-12)0051
2026-05-11Agent Identity & Policy ProvisioningAccepted (Amended 2026-09-29)0057
2026-05-11Agent Portal & Chat UIAccepted0058
2026-05-11Agent Registry & Definition ModelAccepted (Amended 2026-09-29)0050
2026-05-11Agent Workspace ModelAccepted0055
2026-05-11BYOC Agent Discovery & ObservabilityAccepted0056
2026-05-11kora-agents Route & Scope RegistrationAccepted0060
2026-05-11kora-agents Service ArchitectureAccepted0052
2026-05-11Run & Session LifecycleAccepted (Amended 2026-10-12)0053
2026-05-11Sandbox Provisioning and Shell ProxyAccepted0059
2026-05-13Profile Page ArchitectureProposed—
2026-06-04Agents BFF Integration and Run Chat WiringAccepted0061
2026-06-04Service-Layer Authorization for orbit-agentsAccepted0063
2026-06-04Agent Run Filesystem and Process IsolationAccepted (Amended 2026-09-29, 2026-09-30, 2026-10-08)0062
2026-06-04Platform-wide Scope Enforcement MiddlewareAccepted0064
2026-06-04Codex Agent RunnerAccepted (Amended 2026-09-29)—
2026-06-04OpenCode Agent RunnerAccepted (Amended 2026-09-30)—
2026-06-05Inference Log Detail Modal and Failure Details CaptureAccepted0050
2026-06-05LLM Cost Tracking: Pricing Pipeline, Budget Enforcement, and Quota RolesAccepted (Decision 5 superseded 2026-06-10)—
2026-06-06JIT Credential Brokering via a Per-Tenant Egress GatewayProposed (Amended 2026-10-07: Amendment 5 Accepted)0065
2026-06-10Budget Model Redesign: Inline JSONB on Roles/Grants, MAX Resolution, Per-Category SpendProposed—
2026-06-10Budget Enforcement Corrections: Canonical Spend Counter, Request-Time Role Enforcement, All Principal Types, and the Budgets Management SurfaceProposed—
2026-06-10Hierarchical Budget Enforcement: Windows, Pools, Tenant Caps, and Per-Run LimitsProposed—
2026-06-14Agent Sandbox Toolchain and Connectivity EnvironmentsSuperseded by sandbox-environments—
2026-06-12K8s Manifest Field Overrides via Environment VariablesSuperseded by manifest-patches-configmap—
2026-06-15Role-Budget Attribution for Non-Interactive CredentialsAccepted—
2026-06-17Agent Triggers and Webhook IngestionAccepted (Decision item 3 superseded in part 2026-09-29)—
2026-06-19Provider Error Visibility in the Inference GatewayAccepted—
2026-06-19Nav Cleanup and Live DashboardAccepted—
2026-06-19Mobile & Tablet Responsive DesignAccepted—
2026-06-19Run Task SummarizationAccepted—
2026-06-20Trigger Deliveries: Client-Side Status Filter and Inline Payload ExcerptAccepted—
2026-06-20Extended Trigger Types and an Operable Delivery PipelineAccepted (field map, empty event_type rule and declared event types superseded 2026-09-29)—
2026-06-22Model Cost Visibility: Pricing on the Models Page and Virtual Models CatalogAccepted—
2026-06-23Agent Token Breakdown and Spend CardAccepted (Amended 2026-10-06)—
2026-07-04North-South Ingress and External Service ExposureAccepted—
2026-07-06Kubernetes Connection — kubernetes Adapter and Per-Connection Gateway CA TrustProposed—
2026-07-17Agent BuilderAccepted—
2026-07-17Agent Detail Configuration and the Shared Builder MotifAccepted—
2026-07-17Motif Component Promotion into HadesAccepted—
2026-07-22Connection Scope Qualifiers — Grant-Time Resource Scoping for ConnectorsAccepted—
2026-07-22GitHub Connection — Category-Scoped Actions, Repository Qualifiers, and Down-Scoped Token MintingAccepted—
2026-07-23Delegated Agent IdentityAccepted—
2026-07-28OAuth2 Web-Redirect Clients: GitOps Pre-Registration via an OAuthClient CRDAccepted—
2026-08-03Hades Wizard ComponentProposed—
2026-09-06Owner References for Agents and SandboxesProposed—
2026-06-29MCP Server Registration & IntrospectionAccepted (Amended 2026-10-22)—
2026-07-24Non-Token Model Pricing: Full Cost Dimension PipelineAccepted—
2026-06-29MCP / Tool GatewayAccepted—
2026-06-29MCP OAuth Authentication ModelAccepted—
2026-06-30kora MCP — Platform Management MCP ServerAccepted—
2026-07-04North-South Ingress and External Service ExposureAccepted—
2026-07-10Kubernetes-Only Local DevelopmentAccepted—
2026-06-19Multi-Account AWS Bedrock SupportSuperseded by crd-inference-providers—
2026-07-21Alertmanager Webhook AdapterAccepted (curated fields and sub-decision 3 superseded in part 2026-09-29)—
2026-07-21CI Pipeline and Local Build ParallelisationProposed—
2026-09-04Install and Distribution Model: Published Charts and a Tenant-Only OperatorProposed—
2026-09-04Enforcement Sidecar Injection, Preflight and Restricted Pod SecurityAccepted (Amended 2026-10-02, 2026-10-12)—
2026-09-10Database MigrationsProposed—
2026-09-15Config-Driven Kustomize Manifest Patches for orbit-agentsAccepted—
2026-09-16First-Class Customisation Points for Provisioned Agent WorkloadsAccepted—
2026-09-17Tenant MCP Servers as a Recognised Workload ClassProposed—
2026-09-18Authenticated Sandbox Exec and Runner Isolation ParityProposed—
2026-09-18Trace Propagation into the Claude Code Agent RuntimeAccepted—
2026-09-18Telemetry Collector as a Declared Platform DestinationAccepted—
2026-09-28Trigger Payload TemplatingAccepted—
2026-09-29GitHub GraphQL Authorised by the Granular Actions of Selected FieldsAccepted—
2026-09-29Run Activity EventsAccepted—
2026-09-29Agent Run GuardrailsAccepted (Amended 2026-09-30)—
2026-09-30Agent Pod Egress LockdownAccepted—
2026-10-01CRD-Driven Inference ProvidersAccepted (Amended 2026-10-02)—
2026-10-03Sandbox EnvironmentsAccepted (Amended 2026-10-08)—
2026-10-06Rendered Service Config FilesAccepted—
2026-10-07Bundled Sandbox ImagesAccepted—
2026-10-08Sandbox Workspace MountAccepted—
2026-10-10Decision Models and the System One APIAccepted—
2026-10-11Hades Versioning and Theme Surface ManifestAccepted—
2026-10-11Hades Delivery to External ConsumersAccepted—
2026-10-12Run SchedulingAccepted—
2026-10-12White-labelling ThemeAccepted—
2026-10-13Trigger Fire CoalescingAccepted—
2026-10-15Same-Host Connection Selection in the Egress GatewayAccepted—
2026-10-19Trigger RoutingAccepted—
2026-10-19Explain GitHub's Workflow-File Push Refusal at the Egress GatewayAccepted—
2026-10-20Chat Command TriggersAccepted—
2026-10-20Non-Text Model Discovery on Compatible ProvidersAccepted—
2026-10-20Per-Run Cost on the Run RecordProposed—
2026-10-19Repository Id Owner Selection in the Egress GatewayAccepted—
2026-10-20Actions Results Receiver ClassificationAccepted—
2026-10-22MCP Server Static CredentialsAccepted—
—User App PreferencesProposed0061