kaimahi

README

Kaimahi

Agent Builder CLI for Kubernetes.

Getting started · AgentSuite specification · Runtime contract · kmx reference · Contributing

_{About the ketu mark}

---

Kaimahi's kmx CLI helps developers Create → Prove → Lift an agent: write an editable bundle, get a local answer, then move it to a prepared target.

Create, Prove, Lift

Install Docker or Podman (set CONTAINER_ENGINE=podman for Podman), then choose one stable CLI install route (Go needs 1.26+):

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

Stable v0.4.1 first answer: start with the fixed, non-interactive local demonstration:

kmx quickstart

This prepares local kind, Ollama and Orka, then prints a fresh Task's answer; follow getting started to select your own cluster/context.

kmx local up prepares the runtime without creating an agent (unreleased on current main; v0.4.1 uses kmx up).

kmx quickstart --interactive guides custom agent and model choices (unreleased; build current main, or use the stable wizard below).

kmx agent create defaults to Orka and writes an editable bundle on a prepared target.

kmx agent lift moves that bundle to a prepared destination, with Orka as the default.

kmx agent status reports the deployed revision, readiness, drift and available evaluation evidence.

kmx agent evaluate tests the deployed Orka revision (current main also supports an explicitly selected agentsessions host).

Follow the bundle lift guide for target preparation, receipts and evaluation.

Quickstart

For your own agent on stable v0.4.1, run the experimental wizard:

kmx quickstart-wizard

Choose Chat with agent, check a local answer, then enter /lift to a prepared Orka target; after connecting, send a new message to prove it answers there. On current main (unreleased), build with make and use bin/kmx quickstart --interactive instead. See releases and versions for stable installs versus development builds.

Safety: use a dedicated test cluster and review getting started. Both paths create cluster resources and result-reader RBAC; the wizard adds a read-only inventory Tool with cross-namespace permissions. Setup starts while the form is open, and cancellation leaves completed resources in place. Bundle-backed /lift needs a prepared target, a Ready Provider and its Secret, and referenced Tools; it creates neither a cluster nor cloud inference. Hosted model calls can incur charges; review interactive lift for preparation and recovery. kmx down on v0.4.1 (kmx local down on current main) deletes the whole local cluster and its data; export needed data first.

Runtime Contract

Orka is the default runtime; kagent v0.10.3 bundle lift/status is supported on a prepared cluster. See runtime support and bundle lift for flags and limits.

Status

Kaimahi is pre-1.0 and incubating; runtime support and CI evidence records qualified scope, not production readiness or live cloud proof.

Documentation

• Get started with a local first answer.
• Choose models and inference, including Copilot and Foundry.
• Lift a bundle, evaluate a revision, or run evals in CI.
• Inspect targets and runtime support or consult the kmx reference.
• Read the AgentSuite specification for portable artifacts.
• Install or upgrade a release, or review cloud ownership and teardown.
• Browse the documentation index and repository directory map.

Development

From a checkout, make builds bin/kmx without provisioning; follow development and CONTRIBUTING.md for verification and pull requests. The project's cultural and publication boundaries are recorded 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.

Index

• Variables

Variables

var Managed embed.FS

Managed holds managed-cluster provisioning and context-guard scripts. Callers materialize them in a checkout-shaped temporary tree, preserving their relative references and fail-closed shell behavior.

var Manifests embed.FS

Manifests holds the native local model and Orka Kubernetes Tool assets. Explicit paths keep the packaging boundary independent of unrelated checkout additions.