---
title: "Kodama: operator and developer documentation"
description: "Install and use Kodama, the API-first software factory for CI/CD, agentic development, business processes and event-driven automation."
canonical_url: https://optimi.com/en/docs/kodama
md_url: https://optimi.com/en/docs/kodama.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodama
    md_url: https://optimi.com/fr/docs/kodama.md
---

# Kodama

Kodama is an **API-first, Kubernetes-native software factory**. It connects
business requirements to Git-backed workspaces, durable pipelines, agents,
review evidence and controlled delivery. You can use the same execution model
for ordinary CI/CD, agent-assisted development and business automation.

Kodama is published at **[github.com/optimiware/kodama](https://github.com/optimiware/kodama)**
under the **Apache-2.0** license. Install the Helm chart in your Kubernetes
cluster and connect through the CLI or HTTP API.

## Choose your first use case

| Use case | Typical pipeline | What Kodama retains |
| --- | --- | --- |
| Pure CI/CD | Test a commit, build an image, approve and deploy its digest | Source, test reports, image provenance and deployment history |
| Agentic development | Implement a specification, test the candidate and request human review | Pinned instructions/profile, candidate commit, conformance evidence and decision |
| Business process | Validate a request, produce a proposal, approve and apply a change | Business reference, validation report, decision and result receipt |
| Business signals | Receive an event, assess its significance and dispatch an authorized response | Event identity, assessment, deduplicated run and action evidence |

The **[developer guide](/en/docs/kodama/developer-guide)** includes pipeline
examples for all four. A pipeline can run entirely with container steps; an
agent is only needed where model reasoning or tool-assisted work adds value.

## Documentation map

| Page | Purpose |
| --- | --- |
| **Overview** — this page | Understand the product and choose a use case |
| **[Concepts](/en/docs/kodama/concepts)** | Learn tenants, work items, workspaces, runs, attempts, evidence and gates |
| **[Architecture](/en/docs/kodama/architecture)** | Understand the control plane, Kubernetes execution and durable backends |
| **[Getting started](/en/docs/kodama/getting-started)** | Install backend charts and Kodama, authenticate the CLI, register a pipeline and run it |
| **[Developer guide](/en/docs/kodama/developer-guide)** | Author pipelines, integrate business signals and use the API reliably |
| **[Operations](/en/docs/kodama/operations)** | Configure authority and credentials, observe execution, upgrade and recover |

## How you use Kodama

1. **Install a factory.** Provide PostgreSQL, JetStream, object storage, Git,
   an image registry, OIDC and key management, then deploy the Kodama Helm chart.
2. **Create a tenant and project.** Bind users to explicit roles, configure the
   repository and select the execution namespace and delivery targets.
3. **Describe the work.** Record the requested outcome and acceptance criteria.
   Provision its workspace when the workflow needs source continuity.
4. **Register a pipeline.** Define an immutable graph of container steps,
   agent steps and human gates. Pin executable images by digest.
5. **Start a run.** Select the definition, content revision, source commit and
   typed inputs. Supply an idempotency key for reliable submission.
6. **Inspect the outcome.** Follow execution, retrieve evidence, make explicit
   review decisions and promote the identified candidate to a delivery target.

Runs survive client disconnections. A gate can wait for a person without
keeping a container running. Rework starts another run while retaining the
previous source, evidence and decisions.

## What stays under your control

Your organization owns the Kubernetes cluster, repositories, model providers,
tool registrations and deployment credentials. Installation policy sets the
maximum authority; project configuration narrows it. An agent profile cannot
grant itself additional models, tools or runtime permissions.

Kodama separates these responsibilities:

- **Operators** manage backends, identities, runtime policy, encryption and recovery.
- **Administrators** configure tenants, projects, memberships and credentials.
- **Engineers and analysts** define the work, pipelines and acceptance criteria.
- **Reviewers** decide whether identified evidence satisfies an identified subject.

Standalone installations use OIDC plus Kodama memberships. In an Optimi Platform
integration, Platform remains responsible for company-wide tenant authority,
entitlements and commercial access; Kodama provides the software-delivery layer.

## Interfaces

- **CLI:** interactive authentication, work and workspace management, pipeline
  registration, run observation, gates and deployments.
- **HTTP API:** public versioned operations under `/api/v1`, with scoped access,
  resource versions, idempotency keys and resumable event streams.
- **Git:** ordinary developer editing and publication of source commits.
- **Agent integrations:** model gateway and MCP proxy, constrained by installation
  and project policy.
- **Business integrations:** authenticated API callers and configured webhooks
  connect external signals to runs and delivery notifications.

Start with **[the Helm installation walkthrough](/en/docs/kodama/getting-started)**.