Getting started
From an empty Mac to a routable, multi-cluster kind lab in a few
commands. By the end you'll curl a LoadBalancer service by
its real IP — straight from your shell, no port-forwarding.
Prerequisites
- macOS 13 Ventura or later — Apple Virtualization.framework (
vz) is required. - Apple Silicon (arm64). x86_64 is untested.
sudoaccess — prompted once onklimax upto add the host route (and onklimax destroyto remove it).klimax downneeds no sudo.
Docker, kind, kubectl, and the Lima guest agent are downloaded and
provisioned inside the VM on the first klimax up —
you don't install them yourself.
1. Install
The recommended path is the Homebrew cask:
$ brew tap bcollard/klimax
$ brew trust --tap bcollard/klimax
$ brew install --cask klimaxPrefer to build from source? See the README on GitHub.
Already have klimax installed? Upgrading is
brew upgrade --cask klimax followed by a VM rebuild — see
Upgrading klimax.
Shell completion (optional)
# zsh — add to ~/.zshrc to persist
$ source <(klimax completion zsh)2. Bring up the VM
This single, idempotent command creates the Lima VM, installs Docker, applies the L3 networking, and starts the registry mirrors:
$ klimax upThe first run prompts for sudo once — it adds a
macOS route for the kind bridge CIDR (172.30.0.0/16 by
default) pointing at the VM. After that, host→cluster traffic is pure
L3. See Networking & L3 routing.
Already running another Lima-based tool? No action
needed — network.disablePortMirroring defaults to
true, so klimax coexists with Rancher Desktop, Colima, or
another Lima/kind manager out of the box: its kubeconfigs address the
VM's lima0 IP directly instead of racing for
127.0.0.1. Only if you run a single klimax VM and want
stable loopback kubeconfigs should you set it to false in
~/.klimax/config.yaml before your first
klimax up (it's a VM-level setting; changing it later needs
a klimax destroy && klimax up).
Details in Networking.
3. Create your first cluster
$ klimax cluster create devklimax provisions a kind cluster, installs MetalLB with a dedicated IP
pool, wires CoreDNS forwarding, and (by default) merges the new context
into ~/.kube/config. Switch to it like any other context:
$ kubectl config use-context dev
# or, if you use kubectx:
$ kubectx dev4. Prove the routing works
Run the built-in smoke test — it deploys an nginx Deployment and a LoadBalancer Service, then waits for MetalLB to assign a VIP:
$ klimax cluster e2e-test-nginxNow reach that service by its real IP, from your Mac —
no kubectl port-forward:
$ VIP=$(kubectl get svc nginx -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
$ curl http://$VIP/
<!DOCTYPE html> ... Welcome to nginx!That VIP comes from the cluster's MetalLB pool inside
172.30.0.0/16, which your Mac routes directly to the VM.
Pod IPs and Service ClusterIPs are reachable the same way.
5. Go multi-cluster
The whole point of klimax — spin up as many clusters as you need (up to 99). Each gets its own API-server port, subnets, and MetalLB pool:
$ klimax cluster create staging
$ klimax cluster list
$ kubectx staging6. Stop or tear down
# Stop the VM — keeps clusters and the registry cache
$ klimax down
# Delete everything: VM, clusters, and the host route (sudo)
$ klimax destroyWith the default cacheStorage: "host", pulled images
survive even klimax destroy — your next lab rebuilds from
the local cache instead of re-pulling. See Registry mirrors.
Two related lifecycle flows have their own pages: Upgrading klimax (pull a release, then rebuild the VM) and Reset & reinstall (wipe to a clean baseline).
Where to next
- Upgrading klimax — pull a new release and rebuild the VM the right way.
- Reset & reinstall — wipe a bad state and start from a clean baseline.
- Configuration — tune CPUs, memory, the bridge CIDR, kind version, and mirrors.
- CLI reference — every command and flag.
- Networking & L3 routing — how the magic actually works.
- Klimax UI — watch it all from a native macOS app.