Upgrading klimax
Upgrading is two commands: pull the new release, then re-create the VM so it re-provisions on the new version. The image cache survives, so the rebuild is fast.
The two steps
klimax ships as a single binary with its VM provisioning baked in. Bump the binary, then rebuild the VM on it:
# 1. Refresh the tap, then pull the new release
$ brew update
$ brew upgrade --cask klimax
# 2. Rebuild the VM on it (sudo — the host route is re-added)
$ klimax destroy && klimax upbrew update refreshes the bcollard/klimax tap so
Homebrew sees the newest cask version — without it,
brew upgrade may report you're already up to date.
Built from source instead of Homebrew? Replace step 1 with a
git pull and go build (see
Getting started), then run the
same klimax destroy && klimax up.
Always re-create the VM after an upgrade. A plain
klimax down/up only restarts the existing VM —
it does not re-provision it, so Docker, containerd, the guest
agent, and the routing rules keep running the old version until you
destroy and rebuild.
Why a rebuild?
klimax provisions the VM once, on first klimax up: it installs
a specific Docker and containerd, downloads the matching Lima guest agent,
writes the registry-mirror and DNS config, and applies the iptables rules
that make L3 routing work. All of that logic lives in the binary.
A new release can change any of it — a containerd bump, a new
certs.d layout, a routing fix — but an already-provisioned VM
won't pick those changes up just by restarting. Destroying and re-creating
the VM is what re-runs provisioning against the new binary.
What survives, what's recreated
| Item | On destroy && up |
|---|---|
~/.klimax/config.yaml |
Survives. Your CPUs, memory, bridge CIDR, and mirror tweaks are untouched. |
| Registry image cache | Survives with the default cacheStorage: "host" — kept in ~/.klimax/registry-cache/, so the rebuild pulls from local disk, not the internet. |
| Container image store | Recreated by default — it lives on the VM's root disk. Set vm.imageDisk to move it to its own Lima disk and it survives too, unpacked node images included. |
| The VM | Recreated from scratch on the new binary. |
| kind clusters | Removed — cluster state lives inside the VM. Re-create the ones you need afterwards. |
Bring your clusters back with
klimax cluster create <name> once the VM is up — the warm
image cache keeps that quick. Need to wipe config and caches too for a
truly clean slate? See
Reset.
Verify the upgrade
Confirm the new version is running, then check the VM, route, and iptables rules came back healthy:
$ klimax version # confirms the new binary
$ klimax status # VM state, host mounts, clusters, route, iptables
$ klimax doctor # diagnoses issues, prints fix commandsWhere to next
- Changelog — what actually changed between releases.
- Reset — the deeper wipe-and-reinstall levels.
- CLI reference —
up,down,destroy,status,doctor, and every other verb.