kmx-cli-proposal.md

kmx: an agent developer entry point

Status: Proposal

kmx gives developers one command-line entry point for creating and running Kubernetes agents. It packages the working Kaimahi developer journey without replacing Kubernetes, kagent, or the agent YAML.

Quick start

Install the CLI:

brew install kaimahi-agents/tap/kmx

Use an existing Kubernetes cluster:

kmx ctx kind-my-cluster

Or create a local kind cluster with kagent, Ollama, and Kaimahi:

kmx up

Create and run an agent:

kmx agent create hello-world
kmx agent chat hello-world "What can you do?"

kmx agent create uses safe local defaults, writes agents/hello-world.yaml, applies it to the active development context, and waits until the agent is ready. The generated YAML remains the source of truth: developers can edit, diff, review, and reapply it.

Proposed commands

Command	Purpose
kmx ctx <context>	Select and validate an existing Kubernetes context
kmx up	Create a local kind environment and install its dependencies
kmx agent create <name>	Scaffold, apply, and wait for a declarative agent
kmx agent chat <name> <message>	Talk to an agent
kmx status	Show agents, models, tools, and platform health
kmx govern <name>	Enable the Kaimahi governance path for an agent
kmx down	Delete the local environment created by kmx up

Design

kmx is a DevX layer over kind, kubectl, Helm, and kagent. It should:

• make the first successful agent take minutes and a few commands;
• work with either an existing cluster or a disposable local cluster;
• generate portable, reviewable agent YAML rather than hide it;
• show the active context before every mutation and confirm non-local changes;
• delegate runtime-specific operations to kagent or a runtime.

The first milestone is the quick-start path above. Additional Kaimahi capabilities should become kmx commands only after that path is simple, reliable, and useful on its own.