Kaimahi ​

Agent Builder CLI for Kubernetes.

Documentation · Getting started · Workspace lifecycle · Runtime support · kmx reference · Developer guide · Contributing

_{About the ketu mark}

Kaimahi's kmx CLI helps developers author and prove agents for Kubernetes. A workspace is editable source; its prepared AgentSuite is the immutable, content-addressed OCI artifact. The selected runtime owns execution and enforcement.

A workspace does not rename or replace AgentSuite. It is the mutable authoring tree that KMX resolves into the portable AgentSuite artifact used for publication and Lift.

Create, Prove, Lift ​

Create → Prove → Lift is available in v0.6.0 for one-member native Orka and exact-v0.10.3 Go kagent suites. Bounded CI qualifies root Lift for Orka exact reuse, bounded absent-pair registry promotion and kagent fresh-target creation; it does not prove every promotion, creation or partial-outcome path.

Create and push discover the nearest ancestor workspace.yaml; --workspace DIR selects an exact root without fallback. Read the workspace lifecycle for identities, evidence privacy, exact evaluated-subject reuse, absent-only source-evidence --promote, partial outcomes, and fresh-evaluation requirements.

Getting Starter: Get Your First Answer ​

Install Docker or Podman (CONTAINER_ENGINE=podman selects Podman), then choose one independent install route for the latest stable release. Go installs require Go 1.26 or newer:

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

Check what was installed, then run the fixed, non-interactive local proof:

kmx version
kmx quickstart

kmx quickstart creates a local kind environment, starts Ollama and pinned Orka, and succeeds only after a fresh Task returns a readable answer. Use kmx quickstart --interactive for guided native workspace authoring, full eval, publication and reviewed Lift. Follow getting started for prerequisites and explicit context selection.

Workspace And Live Paths ​

Runtime Boundaries ​

A runtime executes and governs the agent. An inference provider is the separate model-access binding; selecting one does not select the other.

• Orka is the default runtime. Its packaged workspace path supports evaluation, evaluated publication and root digest Lift with exact evaluated reuse; independent live Orka run and chat remain.
• kagent support is exact-version and operation-specific: v0.10.3 Go/linux-amd64 packaged workspace authoring, eval --bindings, evaluated publication and create-only root digest Lift. Standalone run/chat, Python, RemoteMCP, suite status and retirement remain unavailable.
• agentsessions supports pinned-chat offline suite create/prepare/load/ordinary push and explicit private eval --development-host FILE: one fresh Session/config/Exec per case, full-pass private proof and exact-S evaluated push. This unauthenticated literal-loopback development path loads no cluster settings; it supports no tools/judge, Lift/chat/status or remote lifecycle. Receipt diff refuses its proof. Read-only reference extraction/export and availability probing remain separate; legacy bundle evaluation/replay is removed.

The runtime support matrix records exact pins and evidence rather than claiming feature parity.

Safety And Status ​

• Readiness, a readable answer, and passing evaluation are different evidence.
• kmx status and kmx orka status report Orka runtime state, not AgentSuite deployment status.
• Quickstart adds cluster resources and result-reader RBAC, then authors, fully evaluates, publishes and Lifts a tool-free native suite. Placement verification precedes its separate fresh answer Task. Console Ready means placement only.
• Chat /lift and console Lift only print Lift moved: kmx lift <ref>@<digest> --to-context … --evidence …; no release GUI or live-copy fallback remains.
• Automatic wizard tools and live tools/inference editing are retired; ordinary host Foundry/Copilot chat controls remain independent.
• Cancellation can leave completed resources in place. kmx local down deletes the entire named local cluster and its data.
• Unsigned evaluation receipts and provenance are observations, not authentication or promotion authority.

Guides ​

Development ​

From a checkout, make builds bin/kmx without provisioning. Start with the developer guide, codebase overview, and interface baseline. The repository map classifies tracked source and scaffolding; contributing defines verification and pull-request expectations. See naming for publication boundaries. Run make docs-preview for the browser-style documentation preview generated directly from these Markdown files.