The wood remembers
Unseen, the wood thinks
branches commit while you sleep
dawn finds the leaves changed
Kodama is an API-first, multi-tenant software factory. Engineers configure projects, pipelines, credentials and guidance; users submit tasks. Container pipelines, agents and ordinary tools produce source changes, tested artifacts and deployed software. Humans answer questions and approve candidates through a role inbox.
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.
The current version is in VERSION. The changes and known
limitations of each version are in CHANGELOG.md.
On Linux with rootless Podman 5:
curl -fsSL https://raw.githubusercontent.com/optimiware/kodama/master/install.sh | sh
kodama up
source ~/.kodama/instances/default/env.shThe first line installs kodama and kodactl into ~/.local/bin.
install.sh downloads them from the latest release for your
system and checks them against the release's SHA256SUMS. kodama up then
starts a complete local Kodama. Run a pipeline file on it:
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 Kodama workload"
EOF
kodactl run hello.yamlexecution execution-a917c44ec73787377abaf074c6b6b61f started
hello from a Kodama workload
execution execution-a917c44ec73787377abaf074c6b6b61f succeeded
The quickstart continues with approvals, tasks, sign-in, Git and MCP.
Without the script: download the kodama and kodactl archives for your
system and SHA256SUMS from the
latest release, then:
sha256sum --check --ignore-missing SHA256SUMS # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf kodama_*.tar.gz && tar -xzf kodactl_*.tar.gz
install -m 0755 kodama_*/kodama kodactl_*/kodactl ~/.local/bin/From a checkout, with Go: make build builds bin/kodama and bin/kodactl;
see the quickstart.
The Podman bundle is a second single-host installation, with a separate
identity provider; the release smoke test runs on it. It installs the released
image (Podman 5, git 2.44, jq, openssl, curl, socat):
git clone --branch v0.2.1 https://github.com/optimiware/kodama && cd kodama
podman pull ghcr.io/optimiware/kodama/kodama:0.2.1
KODAMA_LOCAL_KODAMA_IMAGE=ghcr.io/optimiware/kodama/kodama:0.2.1 ./deploy/podman/install.shThen follow the Podman bundle runbook to run a first pipeline.
| Document | Contents |
|---|---|
| KODAMA.md | The product specification and acceptance criteria. It governs on conflict. |
| docs/README.md | Detailed specifications and runbooks. |
| docs/runbooks/quickstart.md | A local Kodama with kodama up, and a first pipeline with kodactl run. |
| docs/runbooks/podman-quickstart.md | The Podman bundle: the single-host test installation the release smoke runs on. |
| docs/runbooks/production-deployment.md | Deployment on Kubernetes (Scaleway, AWS, GCP). |
| docs/runbooks/release.md | How a version is built and published. |
| Path | Contents |
|---|---|
cmd/kodama |
The server binary: up, server, git, auth, agent, services, migrate, bootstrap-admin. |
cmd/kodactl |
The command-line client. |
api, client |
The public API declarations and the Go client. |
internal |
The Kernel, the Shell and Userland. |
deploy |
The image, the Helm charts, the Podman bundle and the OpenTofu roots per cloud. |
examples |
Example pipelines and knowledge files. |
test |
Contract, component, integration, e2e and qualification suites. |
The Go version is pinned in .go-version.
make build # bin/kodama and bin/kodactl, stamped with the version and revision
make image # the container image of this checkout, which `kodama up` starts
make check # gofmt, vet, unit tests, race tests, architecture and docs checks
make dist # dist/: kodama and kodactl archives, Helm chart packages, SHA256SUMS (needs helm)The suites that need real infrastructure (Podman, kind, the stage) are described in docs/runbooks/unified-test-suite.md.
A kodama (木霊) is a tree spirit of Japanese folklore: it lives in a tree and is seldom seen. The haiku above says what this one does. Pipelines and agents commit to branches while you are away, and when you return you find the result, and whatever waits for your approval.
Ours is a gopher, because Kodama is written in Go. The mascot is inspired by the Go gopher, designed by Renee French and licensed under CC BY 4.0. The icon and the social preview are in docs/assets.
Apache-2.0. See LICENSE.