Skip to content
openwarePublic
forked from optimiware/kodama

About

API-first software factory: pipelines, agents and people shipping software together

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

The Kodama mascot: a small tree spirit shaped like a gopher

Kodama

The wood remembers

Unseen, the wood thinks
branches commit while you sleep
dawn finds the leaves changed

CI Latest release Go version License: Apache-2.0

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.

Status

The current version is in VERSION. The changes and known limitations of each version are in CHANGELOG.md.

Quick start

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.sh

The 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.yaml
execution execution-a917c44ec73787377abaf074c6b6b61f started
hello from a Kodama workload
execution execution-a917c44ec73787377abaf074c6b6b61f succeeded

The quickstart continues with approvals, tasks, sign-in, Git and MCP.

Other ways to install

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

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.sh

Then follow the Podman bundle runbook to run a first pipeline.

Documentation

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.

Repository layout

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.

Build and test

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.

The name

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.

License

Apache-2.0. See LICENSE.

About

API-first software factory: pipelines, agents and people shipping software together

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages