---
title: "Kodema: the open-source software factory"
description: "Kodema runs container pipelines, coding agents and human approvals behind one API. Install it with one command and run a first pipeline in minutes."
canonical_url: https://optimi.com/en/docs/kodema
md_url: https://optimi.com/en/docs/kodema.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodema
    md_url: https://optimi.com/fr/docs/kodema.md
last_updated: 2026-11-14
---

# Kodema

Kodema is an **API-first, multi-tenant software factory**, published under
Apache-2.0 at [github.com/optimiware/kodema](https://github.com/optimiware/kodema).
Engineers configure projects, pipelines and credentials; users submit tasks.
Container pipelines, coding agents and ordinary tools produce source changes,
tested artifacts and deployed software. People answer questions and approve
candidates through a role inbox.

The whole model fits in one sentence: **a pipeline is an ordered list of
actions; an action runs a container or requests an answer; an execution runs a
pipeline once; a task is a conversation that starts executions.**

These pages describe **Kodema 0.2.1**. The
[changelog](https://github.com/optimiware/kodema/blob/master/CHANGELOG.md)
lists the changes and known limitations of each version.

## Try it in two minutes

On Linux with rootless Podman 5:

```sh
curl -fsSL https://raw.githubusercontent.com/optimiware/kodema/master/install.sh | sh
kodema up
source ~/.kodema/instances/default/env.sh
```

The first line installs the `kodema` and `kodactl` binaries into
`~/.local/bin`, after checking them against the release’s `SHA256SUMS`.
`kodema up` then starts a complete local Kodema. Run a pipeline file on it:

```sh
podman pull docker.io/library/alpine:3.24@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
cat > hello.yaml <<'EOF'
actions:
  - name: hello
    image: docker.io/library/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
    timeout: 2m
    commands:
      - echo "hello from a Kodema workload"
EOF
kodactl run hello.yaml
```

```text
execution execution-a917c44ec73787377abaf074c6b6b61f started
hello from a Kodema workload
execution execution-a917c44ec73787377abaf074c6b6b61f succeeded
```

The **[quickstart](/en/docs/kodema/getting-started)** continues with approvals,
tasks, sign-in, Git and MCP.

## How a pipeline runs

**One execution, actions in order**

![A task, a push or kodactl run starts one execution. Its container actions implement and test run in order in a shared workspace, a review request waits for a reviewer without a container, and a pass lets the integrate action run.](/diagrams/kodema/execution-flow-en.svg)

*Actions run one at a time in declaration order. A request waits for a person or a service without holding a container, then the same execution continues in the same workspace.*

A pipeline is a short YAML file. Each container action names an image and the
commands to run in it; each request action names who must answer. There are no
conditions, parallel branches or dependency graphs to learn: conditional
behavior belongs in your scripts.

## What you can build

| Use case | How it looks in Kodema |
| --- | --- |
| Continuous integration | A pipeline with `on.push` starts for each accepted push and runs your test and build commands |
| Reviewed delivery | Build publishes an image digest, a request asks `role/reviewer`, the next action promotes that exact digest |
| Coding agents | Claude Code, Codex, OpenCode or Pi run as ordinary container commands and reach models through Kodema’s proxy, without provider keys in the container |
| Work with people in the loop | A task holds the conversation; an agent can ask a question, hand the work to a person and resume in a fresh execution |
| Automation from your editor | Every operation is also an MCP tool, so an MCP client can start, inspect and approve work |

## Interfaces

- **`kodactl`**, the command-line client: run pipeline files, follow executions,
  read logs, answer the inbox, manage tasks and members.
- **REST API** under `/api/v1`: 58 operations with one request and response
  envelope, idempotency keys and optimistic versions.
- **MCP** at `/mcp`: the same operations as tools, over Streamable HTTP or the
  `kodactl mcp stdio` bridge.
- **Git** (optional): a companion service with gitolite-style access rules and
  approval-guarded branches.

## Documentation map

| Page | Read it to |
| --- | --- |
| **[Quickstart](/en/docs/kodema/getting-started)** | Install Kodema locally, run a pipeline, approve a request, start a task |
| **[Concepts](/en/docs/kodema/concepts)** | Understand pipelines, actions, executions, tasks, requests and roles |
| **[Writing pipelines](/en/docs/kodema/developer-guide)** | Look up the YAML fields, the files a container sees, outputs, and recipes |
| **[CLI reference](/en/docs/kodema/cli)** | Find a `kodactl` or `kodema` command, flag or environment variable |
| **[API and MCP](/en/docs/kodema/api)** | Call Kodema from code: envelope, errors, idempotency, routes, MCP clients |
| **[Architecture](/en/docs/kodema/architecture)** | See how the Kernel, the Shell and Userland fit together |
| **[Operations](/en/docs/kodema/operations)** | Choose an installation, deploy on Kubernetes, upgrade, back up and restore |

## Design choices worth knowing

- **Pipelines are posted through the API.** Files kept in Git are applied with
  `kodactl pipeline apply`; Kodema never discovers pipeline definitions on push.
- **An execution is immutable once admitted.** It keeps the exact YAML, the
  image digests and the inputs it started with. Editing a pipeline does not
  change a running execution.
- **Nothing is replayed blindly.** Rework starts a new execution at the first
  action; an interrupted command is never resumed.
- **Artifacts are values, not entities.** A build publishes bytes to your
  registry and records a digest-pinned reference as an output.
- **Git, agents and model access are optional.** A plain pipeline needs none of
  them.

## Project status

Kodema 0.2.1 runs on a single host with rootless Podman and on Kubernetes
through the Helm charts. `kodema up` has run on Linux only; the macOS binaries
are built and have not been run. Scaleway is the only cloud target that has run
live; AWS and GCP are implemented and not validated against a real cloud. See
**[Operations](/en/docs/kodema/operations)** for the complete list.

Kodema takes its name from the kodama (木霊), a tree spirit of Japanese folklore:
it lives in a tree and is seldom seen. Pipelines and agents commit to branches
while you are away; when you return you find the result, and whatever waits for
your approval.
