Releases, versions and upgrades
Kaimahi is pre-1.0 and incubating. This page is the whole contract: how a version is numbered, how to install one, how to check what you got, how to upgrade, and what happens when an upgrade goes wrong.
@latest and the installer's default select the newest stable tagged release; v0.5.1 includes the Orka v0.2.0 Helm installer, Kubernetes Tool and bundle lifecycle commands. Pin @v0.5.1 for a repeatable build; @main is the moving development option. Orka's own installation and upgrade limits are separate: see orka.md. This release pins the Orka v0.2.0 chart; the historical Kaimahi v0.2.0 release reported Orka v0.1.3.
The official Homebrew namespace is limited to the public kaimahi-agents/homebrew-tap repository and its kmx formula. No trademark is claimed; the remaining publication constraints are recorded in NAMING.md.
Verify a release
Releases built with checksum signing include checksums.txt.sigstore.json, a cosign bundle containing the checksum manifest's signature, signing certificate and transparency-log evidence. The release job uses GitHub Actions OIDC and an ephemeral signing key, not a stored signing secret. Releases published before signing was enabled have no bundle.
With cosign v3.0.6 or newer and GNU sha256sum, choose a signed release and download its four bare binaries, checksum manifest and bundle into an empty directory (the assets are not archives):
version='v<version>'
base="https://github.com/kaimahi-agents/kaimahi/releases/download/$version"
for asset in kmx-linux-amd64 kmx-linux-arm64 kmx-darwin-amd64 kmx-darwin-arm64 checksums.txt checksums.txt.sigstore.json; do
curl -fsSLO "$base/$asset"
done
cosign verify-blob \
--certificate-identity-regexp '^https://github\.com/kaimahi-agents/kaimahi/\.github/workflows/release\.yml@refs/tags/v[0-9][0-9A-Za-z_.-]*$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--bundle checksums.txt.sigstore.json \
checksums.txt && sha256sum -c checksums.txtOn macOS, use shasum -a 256 -c checksums.txt instead of sha256sum -c. Verify the signature before checking digests or running a binary. The identity check accepts only this repo's release workflow running on a version tag.
The signature covers the four binaries, not the separately published kmx.rb formula. install.sh and Homebrew check checksums only; they do not automatically verify this bundle.
Versions
Tags are vMAJOR.MINOR.PATCH, and the tag is the source of truth — the binary reports it, the release is named after it, and the notes come from CHANGELOG.md.
| Below 1.0 that means | |
|---|---|
patch v0.1.0 → v0.1.1 | fixes only: no schema change, no removed flag, no behaviour change an operator was relying on |
minor v0.1.0 → v0.2.0 | everything else, breaking changes included — below 1.0 this is where they live, and the changelog says so under Breaking |
pre-release v0.2.0-rc.1 | a candidate for the version it names. go install …@latest ignores pre-releases, so a candidate never becomes somebody's default by accident |
Orka runtime pins are independent of kmx tags:
| kmx build | Orka install | Offline schema target |
|---|---|---|
| Kaimahi v0.5.1 release | v0.2.0 verified Helm chart, harness-v2 (fullnameOverride=orka-api) | v0.2.0 by default; explicit v0.1.3 or old main snapshot still readable |
| Historical Kaimahi v0.2.0 release | v0.1.3 pinned manifest | historical behavior; not an upgrade path to the current chart |
There is no 1.0 promise and no support window yet. What there is: CI refuses to publish a tag whose version has no section in the changelog, and refuses to publish a binary that does not report its own tag.
Releases use the root vX.Y.Z tag for the repository and CLI. The root is the only Go module; no paired module release tag is needed.
Install
With Homebrew on macOS or Linux:
brew install kaimahi-agents/tap/kmxThe fully qualified name automatically adds the tap and trusts only this formula. It selects the matching one of the four release binaries for the current OS and architecture, then verifies that asset's published SHA-256. The formula checksum detects a changed or truncated download; like install.sh, it is not an independent signature because both originate in the same release. Docker or Podman remains required for local kind workflows.
Upgrade the stable formula with:
brew upgrade kaimahi-agents/tap/kmxThe tap follows stable releases only. Use the versioned installer or pinned Go route below when you need an older release or a prerelease.
The one-line installer for the latest tagged CLI:
curl -fsSL https://raw.githubusercontent.com/kaimahi-agents/kaimahi/main/install.sh | shIt resolves the latest tag, downloads the binary for your platform, verifies its published sha256 before installing it, and puts it in ~/.local/bin without sudo. KMX_VERSION=v0.5.1 pins this release; KMX_BIN_DIR=DIR installs elsewhere. install.sh --quickstart installs the latest release and then launches the non-interactive Orka quickstart. An explicit v0.1.0 --quickstart is still refused because that release predates Orka.
The other route, if you have a Go toolchain:
go install github.com/kaimahi-agents/kaimahi/cmd/kmx@latest@latest is the newest tagged release. Pin instead when you want a build you can name: @v0.5.1. Both go through the public Go module proxy and the Go checksum database, so the bytes you get are the bytes the sum database recorded — no namespace of ours is involved, and there is nothing new to trust.
By hand
install.sh above does exactly this, and doing it yourself is a reasonable preference. Every release carries binaries and a checksums.txt:
version=v0.5.1
base=https://github.com/kaimahi-agents/kaimahi/releases/download/$version
curl -fsSLO "$base/kmx-linux-amd64"
curl -fsSLO "$base/checksums.txt"
want=$(grep ' kmx-linux-amd64$' checksums.txt | cut -d' ' -f1)
got=$(sha256sum kmx-linux-amd64 | cut -d' ' -f1) # macOS: shasum -a 256
[ "$want" = "$got" ] || { echo "checksum mismatch"; exit 1; }
install -m 0755 kmx-linux-amd64 /usr/local/bin/kmxThe comparison is written out rather than left to sha256sum -c on purpose. --ignore-missing is a GNU coreutils flag: macOS has no sha256sum at all (it has shasum), and BusyBox — Alpine, most slim container images — has one that rejects the flag. The instruction that used to be here failed on both, which is a poor first impression from a project whose whole argument is fail-closed verification. install.sh picks whichever of sha256sum, shasum and openssl the machine has, and refuses to install if it finds none.
Do not skip the digest check. The installer verifies the kmx binary before execution, and kmx independently verifies its pinned kind and kubectl downloads (internal/kmx/toolchain); applying less care to its own binary would be indefensible.
Platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64. kmx drives a Linux container runtime, so the machine running it is a Linux host or a Mac running one in a VM. Those are the four release platforms the installer and pinned toolchain support. Windows is served through WSL, which is linux/amd64; a native windows/amd64 build would be an untested claim rather than a platform.
A downloaded CLI needs no Go toolchain for native setup and agent workflows; it still requires the external tools described in getting started.
What did I install?
$ kmx version
kmx v0.5.1 (release build)
kaimahi is pre-1.0 and incubating: minor versions may break behaviour, and say so in CHANGELOG.md
orka v0.2.0
model qwen2.5:3bThe first line is the binary's own identity and it names its source, because the same version string means different things depending on where it came from:
| First line says | You have |
|---|---|
v0.5.1 (release build) | a binary from the release for v0.5.1 |
v0.5.1 (installed with go install) | go install …@v0.5.1 — the same code, built on your machine |
v0.0.0-2026…-fb456eb (development build from a checkout) | a go build from a clone; not a release |
v0.0.0-dev+fb456eb.dirty (development build from a MODIFIED checkout) | a clone with uncommitted changes |
Upgrading kmx
v0.6.0 replaces the legacy user-bundle workflow with one-member, tool-free workspaces. The kmx agent group, bundle commands, user agent.yaml readers/receipts and create --live (including previews and the live wizard) are removed outright, without aliases or migration.
Author source with kmx create NAME --workspace DIR --model MODEL --instructions FILE, then review the instructions and cases. Create, eval and push discover the nearest workspace.yaml; --workspace DIR selects an exact root. Explicit create initializes that root without prompting; nonterminal initialization requires it. Invalid nearest markers and a second member refuse without modifying source.
Evaluate the full workspace with kmx eval, explicit --to-context and a new private --out receipt. Orka uses a Ready openai Provider serving the exact model (--inference provider:NAME); exact-v0.10.3 Go/linux-amd64 kagent uses author-owned --bindings FILE. Publish with kmx push --evaluation FILE REF, which requires full-passing evidence for that exact packaged suite. Ordinary push remains unevaluated.
Deploy with kmx lift REF@sha256:DIGEST, explicit --evidence FILE, --to-context and the matching runtime's inference/bindings selector. Orka can reuse exact evaluated resources; kagent creates new resources only and refuses occupied targets. --plan is GET-only; --promote explicitly permits a matching destination using source-only evidence, not destination evaluation. Lift does not update, adopt, run a model or roll back partial creation. Standalone registry-package evaluation remains unavailable.
Pinned AgentSessions chat is a separate offline packaging and eval --development-host FILE route, with no cluster selectors. It requires an explicit literal-loopback, unauthenticated development host and discloses cleartext journal retention. Its full-pass evidence supports evaluated push, not Lift or receipt diff. See the workspace guide.
Replace removed commands as follows:
| Removed | Use instead |
|---|---|
kmx agent create / kmx create --live | Offline kmx create NAME with exact model and instruction file, then eval/push/Lift |
kmx agent chat/run | Root kmx chat / kmx run --agent NAME for independent live Orka Agents |
kmx agent show/list | kmx orka show/list |
Workspace kmx suite push | kmx push [--workspace DIR] REF; extracted-directory transfer remains |
kmx ctx, root up/down | kmx context show/use, kmx local up/down |
Infrastructure kmx lift/lift down | kmx aks up/down; root digest Lift is deployment only |
Chat /lift / old console Lift | Root digest Lift with explicit evidence; console creation separately composes the native workflow |
Chat/quickstart --azure-discovery | Explicit destination context; provision AKS separately with kmx aks up |
Root status remains the table-only Orka runtime report, also available as orka status, not a suite observer. eval diff/from-sessions remain root helpers, but diff reads only full-passing Orka/kagent suite receipts. Suite status and retirement have no replacement. No old-receipt conversion, automatic migration or saved-file/resource deletion occurs. Preserve old state only with a historical release that understands it. See the v0.6.0 changes and command alignment for the removal policy.
Use @latest for the latest stable release, or pin the version you want:
go install github.com/kaimahi-agents/kaimahi/cmd/kmx@v0.6.0
kmx versionRe-installing upgrades only the CLI; it does not change a running cluster. Read the changelog for versions you skipped: below 1.0 a minor bump may break behavior.
Cluster replacement is separate
v0.6.0 still pins the Orka v0.2.0 verified Helm chart. It does not upgrade existing v0.1.3 manifest installations or foreign releases. Orka ownership now uses kmx.kaimahi.dev/installed; installations with the old kmx.kaimahi.ai/installed in their Helm values are no longer recognized as kmx-owned. Relabeling live objects alone does not change those saved values.
For a disposable local kind cluster you own, export needed data before kmx local down, then kmx local up with the same context/cluster settings. Down deletes the entire cluster, including Tasks, Secrets, PVC-backed data, model data and historical databases. A matching current-label kmx-owned release can still be reused without replacement.
On persistent clusters, plan an operator-managed fresh installation after backing up Orka resources, volumes/PVCs and Secrets, including any existing agent-execution snapshot key. Back up the new chart's orka-api-agent-execution-snapshot key with its controller volume and Orka resources without printing its value. Do not use helm upgrade --force: Orka v0.2.0 supports new installations only. See safe kind and AKS replacement boundaries.
KMX does not install or upgrade kagent. Its exact-v0.10.3 Go suite path requires an operator-owned runtime; v0.10.2 live create is removed.
Cutting a release
For maintainers. The point of this list is that the second release is cheaper than the first.
Write the section. Move what is under
## Unreleasedin CHANGELOG.md into a## vX.Y.Z — <date>heading, and leave## Unreleasedempty behind it. Anything breaking goes under Breaking with what to do about it; anything that changes an operator's day goes under Upgrading.Merge that to
main. Releases are cut frommain.Tag the root CLI release and push:
bashgit tag vX.Y.Z git push origin vX.Y.ZWatch the
releaseworkflow. It builds through GoReleaser, checks that exact artifact set, then publishes those same files together as one GitHub release. It refuses to publish if: the version is not semantic, the changelog has no section, the built binary does not report the tag, or the checksums do not verify. The release also carrieskmx.rb, GoReleaser's rendered formula for those exact checksums (brews.skip_upload: truekeeps it from being pushed to the tap on its own — that stays a human's job, next). A failed asset upload can leave a GitHub draft; inspect and remove that incomplete draft before rerunning the tag workflow. For a stable release, download the exact formula asset and submit it as the change in the official tap:bashtap=$(mktemp -d) git clone https://github.com/kaimahi-agents/homebrew-tap.git "$tap" formula=$(mktemp) gh release download vX.Y.Z --repo kaimahi-agents/kaimahi \ --pattern kmx.rb --output "$formula" --clobber mv "$formula" "$tap/Formula/kmx.rb" cd "$tap"From that tap checkout, create a branch, commit
Formula/kmx.rb, and open a pull request tokaimahi-agents/homebrew-tap. Its CI (.github/workflows/tests.ymlin that repo) runsbrew style,brew audit --strict --online,brew readall,brew install, andbrew teston macOS and Linux — that is what "review and the tap's formula checks pass" means, and it is the actual gate; GoReleaser rendering cleanly is necessary but not sufficient. To rehearse the same checks locally before opening the PR (catches issues without waiting on that CI). Run this from the candidate tap checkout created in step 4. It refuses to replace an installedkmxkeg, preserves any existing tap checkout, and keeps the temporary trust entry outside your normal Homebrew configuration:bash( set -euo pipefail candidate=$PWD tap_name=kaimahi-agents/tap formula="$tap_name/kmx" tap_parent="$(brew --repository)/Library/Taps/kaimahi-agents" tap_dir="$tap_parent/homebrew-tap" if brew list --formula --versions kmx 2>/dev/null | grep -q .; then echo "refusing to replace installed kmx; use a clean Homebrew installation" >&2 exit 1 fi mkdir -p "$tap_parent" backup_root=$(mktemp -d "$tap_parent/.kmx-tap-backup.XXXXXX") saved_tap="$backup_root/homebrew-tap" trust_home=$(mktemp -d) had_tap=false candidate_linked=false install_started=false cleanup() { local status=$? if [ "$install_started" = true ]; then if ! brew uninstall --force "$formula" >/dev/null 2>&1; then echo "failed to uninstall candidate $formula; remove it manually" >&2 status=1 fi fi if [ "$candidate_linked" = true ] && [ -L "$tap_dir" ]; then rm "$tap_dir"; fi if [ "$had_tap" = true ] && { [ -e "$saved_tap" ] || [ -L "$saved_tap" ]; }; then mv "$saved_tap" "$tap_dir" fi rm -rf "$backup_root" "$trust_home" exit "$status" } trap cleanup EXIT if [ -e "$tap_dir" ] || [ -L "$tap_dir" ]; then mv "$tap_dir" "$saved_tap" had_tap=true fi mkdir -p "$tap_parent" ln -s "$candidate" "$tap_dir" candidate_linked=true export XDG_CONFIG_HOME="$trust_home" brew trust --tap "$tap_name" brew style "$formula" brew audit --strict --online "$formula" brew readall --os=all --arch=all "$tap_name" install_started=true brew install "$formula" kmx_prefix=$(brew --prefix "$formula") installed_version=$("$kmx_prefix/bin/kmx" version | sed -n '1s/^kmx v\([^ ]*\) (release build)$/\1/p') formula_version=$(brew info --json=v2 "$formula" | brew ruby -rjson -e 'puts JSON.parse(STDIN.read).fetch("formulae").first.fetch("versions").fetch("stable")') test -n "$installed_version" test "$installed_version" = "$formula_version" brew test "$formula" )Merge the PR only after review and the tap's actual CI (not just this rehearsal) passes. Prerelease formula assets are inspection evidence and do not replace the stable formula.
Check the result with both routes:
go install …/cmd/kmx@vX.Y.Z && kmx version, then the following on a clean Homebrew installation:bashbrew install kaimahi-agents/tap/kmx && kmx_prefix="$(brew --prefix kaimahi-agents/tap/kmx)" && "$kmx_prefix/bin/kmx" version
To rehearse without spending a version number, run the release workflow manually (workflow_dispatch) from a branch: it builds and checksums exactly the same artifacts, renders the candidate formula, publishes nothing, and uploads them as workflow artifacts. Prereleases publish their own formula asset for inspection but never replace the tap's stable formula.