---
title: "Kodama: durable agent execution"
description: "A high-level overview of Kodama, the Go runtime for durable agent sessions, parallel execution and optional coding workspaces on PostgreSQL and NATS."
canonical_url: https://optimi.com/en/docs/kodama
md_url: https://optimi.com/en/docs/kodama.md
last_updated: 2026-10-23
---

# Kodama

Kodama is a **Go runtime for durable, parallel agent execution**. It embeds in
your application so you can submit work, disconnect, restart workers and return
to the same session with its recorded history intact.

It provides the agent-execution foundation for Optimi’s software-factory
approach. Your application supplies the business workflows, models and tools;
Kodama coordinates execution and recovery.

> **Public repository coming soon**
>
> The repository is planned at **`github.com/optimiware/kodama`**. It has not
>   been published yet.

## What Kodama provides

- **Durable sessions:** submit tasks, inspect progress and append more work to
  an existing session.
- **Parallel execution:** run independent sessions across workers while
  preserving the order of inputs within each session.
- **Controlled tools:** define the tools an agent can use, set execution limits
  and request human approval for selected actions.
- **Optional coding workspaces:** let agents inspect repositories, make changes
  and run tests in a separate execution environment.

## Architecture at a glance

Kodama fits into the infrastructure and application lifecycle you already own.

| Component | Role |
| --- | --- |
| **Host application** | Authentication, tenant identity, business endpoints, secrets and deployment |
| **Client** | Accept tasks, read session history and request pause, resume or cancellation |
| **Workers** | Execute model and tool steps, enforce limits and recover interrupted work |
| **PostgreSQL** | Authoritative session state, execution history and recovery records |
| **NATS JetStream** | Optional wake-up notifications that help workers discover available work promptly |

PostgreSQL is the source of truth. Workers also check it directly, so a temporary
NATS outage does not lose accepted tasks. A deployment can run with PostgreSQL
alone; NATS adds notifications, and NATS Core can carry provisional live output.

## How a task runs

1. Your application authenticates the request, selects a tenant and opens a
   session with a versioned agent definition.
2. The client records the input in PostgreSQL and returns a run identifier.
   The run continues independently of the original HTTP connection.
3. A worker executes the model and authorized tools, recording completed steps.
   Work can wait for a tool result or a human approval and resume later.
4. Final output and history remain available to your application. Operators can
   inspect or control the session, and users can submit the next task.

Recovery resumes from committed state. If an external action’s result is
uncertain, Kodama records that uncertainty for reconciliation rather than
blindly repeating the action.

## Coding and application integration

Coding support adds a workspace provider and optional artifact storage. Agents
can read and edit files, execute bounded commands and return diffs, test results
or artifacts. Checkpoints preserve work across interruptions. Parallel coding
sessions use separate writable workspaces with an explicit review and merge step.

Your application owns authentication, permissions and publication policy.
Git publication and production releases belong to explicitly authorized
workflows. Model and tool adapters connect Kodama to the providers and systems
you choose; MCP can be used as a tool adapter.

## Deployment and operations

Run the client and workers in one Go service, or separate the API from a pool
of workers. Both patterns fit customer-controlled cloud or on-premise
environments.

The current technical baseline is **Go 1.26+ and PostgreSQL 16+**, with
**NATS Server 2.10+** when NATS is used. The host owns connections, explicit
database migrations, configuration and shutdown.

Set queue, concurrency and execution limits for your workload. Health and
diagnostic interfaces expose readiness, backlog, missing capabilities and
unresolved tool outcomes. Logs and hooks integrate with your monitoring stack.

## Working with Optimi

Optimi can help integrate Kodama into your enterprise chassis, configure
modernization projects and train your team to supervise and operate the factory.

- [Explore Legacy Modernization](/en/solutions/legacy-modernization).
- [Talk to an Optimi Architect](/en/contact).