kaimahi

<div align="center"> <img src="brand/ketu.svg" alt="Kaimahi ketu mark" width="128" /> # Kaimahi **Agent Builder CLI for Kubernetes.** [](https://github.com/kaimahi-agents/kaimahi/actions/workflows/ci.yml) [](https://github.com/kaimahi-agents/kaimahi/releases) [](LICENSE) [Getting started](docs/getting-started.md) · [Runtime contract](docs/runtime-adapters.md) · [`kmx` reference](docs/kmx.md) · [Contributing](CONTRIBUTING.md) _{[About the ketu mark](brand/README.md#ketu-mark)} </div> --- 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 Install Docker or Podman (set `CONTAINER_ENGINE=podman` for Podman), then choose one CLI install route (Go requires 1.26+): ```bash brew install kaimahi-agents/tap/kmx # or curl -fsSL https://raw.githubusercontent.com/kaimahi-agents/kaimahi/main/install.sh | sh # or go install github.com/kaimahi-agents/kaimahi/cmd/kmx@v0.4.1 ``` To create your own agent and hear it answer locally, follow the interactive journey below. For a fixed, non-interactive hello-world demonstration instead: ```bash kmx quickstart ``` `kmx quickstart` provisions local kind and Orka and runs a fixed Agent's fresh Task. `kmx up` provisions the local runtime without creating an Agent. `kmx quickstart-wizard` is the custom interactive path: ```bash kmx quickstart-wizard ``` Create an agent, choose **Chat with agent**, get a local answer, then enter `/lift`. After connecting, send a new message to confirm the lifted agent answers; follow [getting started](docs/getting-started.md) for the steps. `kmx agent create` defaults to Orka, writes an editable bundle, and preserves all existing no-flag behavior. The explicit `kmx agent create --runtime kagent <name>` path is a narrowly scoped, create-only integration for an already-installed exact Kagent v0.10.2, with an optional single A2A message as part of that create invocation; KMX never installs or upgrades it. `kmx agent lift` and interactive `/lift` deploy Orka bundles only to a prepared Orka target; the console offers a separately confirmed preparation step when Orka or the quickstart Tool is missing. `kmx agent status` reads its revision, readiness, drift and evaluation result. `kmx agent evaluate` runs the bundle's cases against that deployed revision. See the [bundle lift guide](docs/agent-lift.md) for target preparation, receipts and evaluation. If no local bundle exists, `/lift` labels its live-copy fallback; that result is not tracked by status or evaluate. ## Quickstart The fixed first-answer path uses local kind, Ollama, Provider and Agent. The wizard prepares a local Kubernetes target while you describe your own agent. Bundle-backed `/lift` selects an existing Ready destination Provider; create one first if none is available. Only the labelled bundle-less live-copy route can create new cloud inference, which can incur charges. Read the [interactive lift guide](docs/interactive-lift.md) for behavior and recovery. Both paths create local cluster resources and result-reader RBAC. They install the pinned v0.2.0 Orka Helm chart in harness-v2 mode, with CRDs applied from the verified chart and an encryption key generated by Orka (never printed by kmx). The wizard also installs a read-only Kubernetes inventory Tool. KMX installs an exact same-namespace `OutboundAccessPolicy` for Orka to reach the Tool's private Service and waits for both the policy and Tool to be ready. A missing or invalid policy fails closed rather than falling back to the Tool's logical public URL. The non-interactive first-answer path does not use that Tool. Completed setup can remain after cancellation. Read [getting started](docs/getting-started.md) before using it on a shared machine. Use Podman explicitly with: ```bash kmx --container-engine podman quickstart-wizard ``` `@main` remains the moving development option; use `@v0.4.1` for this release. From a checkout, `make` builds `bin/kmx` without provisioning anything. ## Runtime Contract [Orka](https://github.com/orka-agents/orka) remains the first-class and default runtime. The explicit Kagent v0.10.2 create capability does not change any no-flag workflow or add Kagent installation, discovery, chat, inspection, lift, evaluation, console, quickstart, `up`, or AKS payload support. The selected runtime owns execution and enforcement; runtime choice and model provider are separate. Read the [runtime adapter contract](docs/runtime-adapters.md) 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` | Orka is the unchanged default; explicit `--runtime kagent` is create-only for exact v0.10.2. Neither path provisions credentials | | Prove an answer | Interactive Orka chat or `kmx agent create --task ...` | Readiness alone is not execution proof; Kagent sends one A2A message and never retries an ambiguous result | | Lift a bundle to a prepared target | `kmx agent lift <bundle-dir> --to-context <ctx> --inference provider:<name>` | Orka bundles only; reconciles on an existing target and `--plan` writes nothing | | Compare Git and deployed revisions | `kmx agent status <bundle-dir> [--to-context <ctx>] [-o table\|json]` | Orka bundles only; read-only per-target revision, readiness, drift and evaluation | | Check a revision before promoting it | `kmx agent evaluate <bundle-dir> [--to-context <ctx>] [--case <id>]` | Orka bundles only; runs `eval/*.yaml` cases as Tasks and exits non-zero unless all pass | | Lift an agent interactively | `/lift` in chat or console | Orka only; deploys the local bundle through the same lift as the CLI, with an untracked labelled live-copy fallback when no bundle exists | | Inspect agents | `kmx agent list`, `show`, and interactive `chat` | Orka-only; list/show/chat default to `orka-system`, while both create paths require `--namespace` | | Provision an AKS target | `kmx aks up` | Billable platform workflow; does not create the agent | Default Orka create writes reviewable YAML, validates it against the selected target, creates dependencies in order, and waits for current-generation readiness. Its real answer requires `--task` plus pre-existing result access. Explicit Kagent create writes a review artifact and portable bundle; `--out -` omits the bundle unless `--bundle-path` is set. Offline rendering requires neither an installed Kagent nor a cluster Secret. Online creation requires both, and creates only a new ModelConfig and Agent; it never adopts, updates, or rolls back. Kagent bundles are intentionally refused by the currently Orka-only lift, status, evaluate, console, and interactive `/lift` paths. 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](docs/kmx.md#kmx-agent-create). ## Lifecycle Orka bundles, lift receipts, revision-aware status and evaluation are available as standalone commands. Only a successful online Kagent create writes its own private, prompt/answer-free receipt. Lift, status, and evaluation remain Orka-only. The [lifecycle direction](https://github.com/kaimahi-agents/kaimahi/issues/194) also discusses rollback, which does not have a standalone command. Deploying and verifying an earlier revision cannot undo an agent's completed external actions. KMX uses Git and the selected runtime rather than a separate server. ## Migrate Model Traffic `kmx migrate` is a separate compatibility bridge for an existing application: ```bash 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](docs/migrate.md) for protocol, credential, and ownership limits. ## Status Kaimahi is pre-1.0 and incubating. Interactive local creation, default creation on the first-class Orka runtime, inspection, chat, bundle lift and interactive lift to an existing target, AKS platform provisioning, and model-traffic migration are implemented. The only current Kagent capability is explicit, create-only authoring for an already-installed exact v0.10.2, optionally ending in one A2A message from that invocation. Its former broad command surface remains retired, and historical AKS records remain teardown-only. Rollback remains directional; 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](docs/getting-started.md) | Prerequisites and current local workflows | | [`kmx` reference](docs/kmx.md) | Commands, safety rules, and output contracts | | [Runtime contract](docs/runtime-adapters.md) | Runtime, context, session, inference, lifecycle, and enforcement boundaries | | [Runtime setup](docs/orka.md) | First-class default implementation setup, native creation, and first task | | [Bundle lift](docs/agent-lift.md) | Standalone bundle-to-prepared-target command and receipts | | [Interactive lift](docs/interactive-lift.md) | Bundle lift with guided preparation and the labelled live-copy fallback | | [AKS](docs/aks.md) | Billable resource ownership, provisioning, and teardown | | [Migration](docs/migrate.md) | Existing-application model-traffic bridge | | [Releases](docs/releases.md) | Versioning, install/upgrade paths, and cutting a release | | [Direction issue #194](https://github.com/kaimahi-agents/kaimahi/issues/194) | Proposed definitions, adapters, and lifecycle | | [Documentation index](docs/README.md) | All current guides and maintainer references | ## Development Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [developer entry-point principles](docs/entry-point-principles.md). 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](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](https://github.com/kaimahi-agents/kaimahi/issues) > 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](docs/runtime-adapters.md) for the current boundary.