---
title: "Kodama architecture"
description: "Understand how Kodama connects its API and Kubernetes workloads to PostgreSQL, JetStream, Git, object storage, model providers and human review."
canonical_url: https://optimi.com/en/docs/kodama/architecture
md_url: https://optimi.com/en/docs/kodama/architecture.md
last_updated: 2018-10-20
---

# Architecture

Kodama separates **the control plane**, which owns authorization and durable
state, from **execution workloads**, which run your commands and agents. Helm
deploys the control plane and tenant execution policy; the server creates an
ordinary Kubernetes Job for each executable step attempt.

## System map

**One control plane, scoped execution**

![CLI and API integrations authenticate through OIDC and reach the Kodama control plane. The control plane uses PostgreSQL, JetStream, Git and S3, and dispatches tenant Jobs whose callbacks, models and tools use scoped interfaces.](/diagrams/kodama/architecture-en.svg)

*Durable state and credentials stay behind the control plane. Tenant Jobs receive only the authority required by their attempt.*

The initial chart runs one server replica with a `Recreate` rollout strategy.
PostgreSQL and JetStream are separately operated services. Git, S3-compatible
object storage, an OCI registry, OIDC and a cloud KMS complete the installation.

## What each backend owns

| Backend | Data and responsibility | What to preserve |
| --- | --- | --- |
| PostgreSQL | Work, runs, attempts, memberships, configuration, gates, deployment records, audit and event coordination | Database backups and WAL, with the matching source, objects and keys |
| NATS JetStream | Durable transport for domain events and worker coordination | Streams and durable consumers, backed by outbox/inbox recovery |
| Git | Accepted commits, work branches and protected run references | Every commit still referenced by a run, review, release or recovery point |
| S3-compatible storage | Reports, traces, artifacts and retained logs | Object bytes and their verified digests |
| OCI registry | Executable images and deliverables | Images pinned by digest for execution and supported releases |
| KMS | Wrapping keys for encrypted scoped credentials | All key versions required to decrypt live and recoverable records |

PostgreSQL is the state authority. A transaction records its business change
and event in an outbox together; a publisher delivers committed events to
JetStream. Consumers use inbox records to deduplicate delivery. Reconciliation
covers missed notifications and interrupted work. A broker outage does not
erase accepted work, but JetStream remains a required backend.

## The life of an attempt

1. **Admission:** authenticate the caller, check project authority and limits,
   then pin the definition, source, content revision and configuration.
2. **Dispatch:** commit an attempt claim and ask Kubernetes to create or adopt
   its deterministically named workload outside the database transaction.
3. **Runtime admission:** bind the workload identity and exchange admission
   material for a short-lived attempt token.
4. **Execution:** `kodama step` prepares source, launches the declared command
   and collects results within the configured resource and time limits.
5. **Publication:** reserve and upload artifacts; for a writer, propose source
   and compare the expected remote Git tip before publishing.
6. **Finalization:** validate authority, output types, artifact provenance and
   publication outcome before committing the step’s result.
7. **Settlement:** reconcile cancellation or uncertainty, retain logs and remove
   workloads whose durable outcome is settled.

A lost response does not prove failure. The next control-plane process observes
the matching workload or remote effect before deciding whether another action
is required. A foreign Job with the same name is not adopted. A cancelled
attempt cannot finalize a new result using an old token.

## Git workspaces and execution storage

A workspace is a logical source context, not a persistent development Pod.
Each attempt receives private scratch space and a pinned source commit. Git
holds accepted checkpoints; S3 holds retained outputs. Deleting scratch space
therefore does not remove accepted source or reports.

Read steps cannot publish. Writers are ordered and use expected-tip publication
so a concurrent human push is detected rather than overwritten. Later readers
choose either the run’s original commit or the commit of an ancestor writer.
Branch movement never silently changes an existing run’s inputs.

## Isolation and credentials

Authorization applies to API reads and writes, logs, events, artifacts and
source. Tenant/project ownership follows every resource. The serving PostgreSQL
role is a non-owner without superuser or `BYPASSRLS` privileges; migrations use
a separate owner identity.

Kubernetes execution uses tenant namespaces, restricted Pod Security, quotas,
bounded volumes, tokenless workload service accounts and explicit network
egress. Workloads do not receive the control plane’s database, NATS or cluster
credentials. This is the trusted-engineer execution profile on ordinary
containers; namespace separation is not a general sandbox for hostile public code.

Secrets are versioned references. Admission pins the authorized version;
read-for-use rechecks authority. A deployment receives only its target’s scoped
credentials. Keep secret values out of pipeline documents, source commits and
output artifacts.

## Models and tools

An agent profile selects a qualified harness image, instructions, model, tools
and limits. The agent runs as an ordinary attempt. Its model requests pass
through an OpenAI-compatible gateway; external tools pass through an MCP proxy.
Provider credentials remain server-side.

Installation policy defines allowed destinations, wrapper capabilities and
runtime actions. Project model settings and tool registrations narrow those
choices. Revoking approval prevents new use without rewriting historical runs.
An interrupted model stream or an unknown tool outcome is recorded explicitly;
a potentially side-effecting tool call is not blindly repeated.

## Integration boundaries

| Interface | Caller and purpose |
| --- | --- |
| `/api/v1` | Human users and authenticated integrations: work, pipelines, runs, gates and delivery |
| Project/run event streams | Authorized observers using durable cursors and `Last-Event-ID` |
| `/runtime/v1` | Attempt-scoped entrypoints: admission, pinned context, artifacts and results |
| Model gateway / MCP proxy | Authorized agent attempts using their runtime token |
| Git hook / business adapter | Authenticated signals mapped to an exact source or typed run inputs |
| Outbound ChatOps | Durable notifications containing links to authenticated resources |

Integrators use the [public OpenAPI document](https://github.com/optimiware/kodama/blob/main/api/openapi.yaml)
or the generated client. They do not connect directly to Kodama’s tables or
publish internal events as a substitute for authorized API operations.

Continue with **[Helm installation](/en/docs/kodama/getting-started)** or
**[pipeline examples](/en/docs/kodama/developer-guide)**.