kaimahi

README

Kaimahi

Agent Builder CLI for Kubernetes.

Getting started · Runtime contract · kmx reference · Contributing

_{About the ketu mark}

---

Kaimahi's kmx CLI helps developers create an agent, prove it locally, and move it into a real environment without learning each runtime's manifests first.

Create, Prove, Lift

kmx agent create
kmx agent lift

create is the path from an idea to an editable local agent. lift is the path from "it works here" to a selected Kubernetes or AKS environment. KMX keeps the target and changes explicit while the runtime handles execution.

These are the simple commands KMX is converging on. kmx agent create exists today for a prepared target. A standalone kmx agent lift is not implemented yet; the current lift is available as /lift from interactive chat. See the lifecycle direction.

Quickstart

Install Docker, then use the checksum-verified release installer:

(
  installer=$(mktemp) || exit
  trap 'rm -f "$installer"' EXIT
  curl -fsSL https://raw.githubusercontent.com/kaimahi-agents/kaimahi/main/install.sh -o "$installer" || exit
  sh "$installer" --quickstart
)

A failed download stops before running any installed binary; the temporary script is removed after quickstart. On a Podman-only machine, replace the last sh "$installer" --quickstart with CONTAINER_ENGINE=podman sh "$installer" --quickstart.

Or, with Go 1.26+, build the same release and run that exact binary:

GOBIN="$HOME/.local/bin" go install github.com/kaimahi-agents/kaimahi/cmd/kmx@v0.2.0 && "$HOME/.local/bin/kmx" quickstart

kmx quickstart is a non-interactive Orka path through local kind, Ollama, Provider, Agent and a fresh Task to a readable answer. kmx up provisions the runtime without creating an agent. To choose your own model and agent interactively, run kmx quickstart-wizard; it prepares a local Kubernetes target while you describe the agent. To complete the wizard journey:

1. Choose Chat with agent when setup is ready.
2. Send a prompt and wait for an answer to prove the selected execution path.
3. Enter /lift, choose an existing Kubernetes or AKS target, review the destination and inference choice, then confirm.

The current lift reads the live source agent, deploys to an existing target, and does not replay a task or delete the source. Choosing new cloud inference can create billable resources. Read the interactive lift guide for the complete behavior and recovery boundaries.

Both paths create local cluster resources and result-reader RBAC. The wizard also installs a read-only Kubernetes inventory tool, but Orka v0.1.3 refuses its in-cluster Service URL (tool URL resolves to private/loopback IP). The tool never becomes Available to Orka-executed Tasks; see known issue #217. The non-interactive first-answer path does not use that tool. Completed setup can remain after cancellation. Read getting started before using it on a shared machine.

Use Podman explicitly with:

kmx --container-engine podman quickstart-wizard

@main remains the moving development option; use @v0.2.0 for this release. From a checkout, make builds bin/kmx without provisioning anything.

Runtime Contract

Orka is the first-class runtime. The selected runtime owns execution and enforcement. Read the runtime adapter contract for the boundaries between KMX and runtimes.

Current Commands

Goal	Current interface	Boundary
Prove the fixed local first-answer path	kmx quickstart	Non-interactive Orka Agent and fresh Task
Provision the local runtime only	kmx up	Does not create an agent
Create your own local agent interactively	kmx quickstart-wizard	Wizard with model and agent choices
Create on a prepared target	kmx agent create	Does not install the runtime or provision credentials
Prove an answer	Interactive chat or kmx agent create --task ...	Readiness alone is not execution proof
Lift an agent	/lift in interactive chat	Uses a live agent and an existing destination
Inspect agents	kmx agent list, show, and interactive chat	Orka-only; list/show/chat default to orka-system, while create requires --namespace
Provision an AKS target	kmx aks up	Billable platform workflow; does not create the agent

kmx agent create writes reviewable YAML, validates it against the selected target, creates dependencies in order, and waits for current-generation readiness. A real answer requires --task plus pre-existing result access. Credentials, namespaces, and RBAC remain separate operator responsibilities. Use --out - or --no-apply for offline output and --dry-run for server admission without cluster writes. Read the complete agent create contract.

Lifecycle

The simple front door does not remove deeper lifecycle needs. The direction in #194 includes Git-tracked agent definitions, immutable revision digests, deployment receipts, evaluation, target-aware status, diff, and rollback.

Those operations do not have full standalone command parity on main. The initial state model should use Git and the selected runtime rather than introduce a second KMX server or controller. Rollback means deploying and verifying an earlier revision; it cannot undo external actions already completed by an agent.

Migrate Model Traffic

kmx migrate is a separate compatibility bridge for an existing application:

kmx plane
kmx migrate <deployment> --namespace <namespace> --model <provider>/<model>

The application owner keeps the Deployment and reviews the generated patch. The bridge covers a supported model-client shape; it does not convert the application into an agent, govern all of its activity, or replace runtime enforcement. Read the migration guide for protocol, credential, and ownership limits.

Status

Kaimahi is pre-1.0 and incubating. Interactive local creation, creation on the first-class runtime, inspection, chat, lift to an existing target, AKS platform provisioning, and model-traffic migration are implemented. Standalone agent lift and the complete lifecycle remain directional. The legacy runtime's commands are retired; the model-traffic bridge (kmx plane, kmx migrate) remains. AKS paths use billable resources and are not continuously re-proved in CI.

Documentation

Start here	Purpose
Getting started	Prerequisites and current local workflows
kmx reference	Commands, safety rules, and output contracts
Runtime contract	Runtime, context, session, inference, lifecycle, and enforcement boundaries
Runtime setup	First-class implementation setup, native creation, and first task
Interactive lift	Current agent-to-target behavior
AKS	Billable resource ownership, provisioning, and teardown
Migration	Existing-application model-traffic bridge
Direction issue #194	Proposed definitions, adapters, and lifecycle
Documentation index	All current guides and maintainer references

Development

Read CONTRIBUTING.md and the developer entry-point principles. Changes land through pull requests to main with checks green and verification actually run. The project name's cultural and publication boundaries are documented in docs/NAMING.md.

[!IMPORTANT] Kaimahi is experimental and under active development. Commands, generated artifacts, and behavior may change between pre-1.0 releases. It is not yet recommended for production use. Use a dedicated test environment, review every proposed mutation, and open an issue with feedback, bugs, or ideas.

[!NOTE] KMX is the Agent Builder and lifecycle layer, not a runtime or generic governance control plane. The selected runtime owns execution and enforcement. See the runtime contract for the current boundary.

Documentation

Overview

Package kaimahi embeds the assets kmx needs when installed without a checkout. Embedded paths are relative to this module root and cannot cross into plane/.

Index

• Variables

Variables

var Managed embed.FS

Managed holds managed-cluster observability, model egress and installer scripts. Callers materialize the scripts in a checkout-shaped temporary tree, preserving their relative references and fail-closed shell behavior.

var Manifests embed.FS

Manifests holds the runtime kmx installs and the model plane it deploys. Explicit paths keep the packaging boundary independent of unrelated checkout additions.

What is NOT here any more: the legacy runtime's Helm values, its two demo agents, and the k8s/models model presets. All five belonged to a runtime kmx no longer installs, and nothing applied them — `kmx plane` applies k8s/plane/, and `kmx migrate` writes a Secret into the operator's own namespace.