Kubernetes that runs natively on your Mac. kvz is a single binary, in the spirit of k3s. The whole control plane (etcd, the API server, the scheduler and the controllers) runs as one ordinary macOS process, with no Linux VM underneath. Your pods run as:
- Linux pods. Each one is its own lightweight VM, ready in about 100 ms.
- macOS pods. A full macOS virtual machine you can
kubectl execinto. - Native pods. Plain macOS processes, for Xcode builds, code signing or anything that needs the real Mac.
You use it with the same kubectl and YAML you already know.
You need an Apple Silicon Mac running macOS 26 or later.
brew install kvz-platform/tap/kvz
kvz server # starts the cluster and prints how to connectIn a second terminal:
export KUBECONFIG=~/.kvz/kubeconfig.yaml
kubectl run web --image=nginx:alpine
kubectl get podsThat pod is a fresh Linux VM. The getting started guide covers macOS and native pods, adding more Macs, running kvz in the background, and building from source.
kvz is measured against k3s in Lima and Apple's container cluster on
three M4 Mac minis and a Mac Studio. It's faster on every lifecycle metric we
measured: startup, idle cost, API throughput, pod start, bursts and teardown.
It's slower at pod-to-pod bandwidth, because every pod is its own VM. No VM
pools, snapshots or pre-started pods are used to get these numbers.
Full tables and method: docs/BENCHMARKS.md.
| Guide | What's in it |
|---|---|
| Getting started | Install, run your first pods, add Macs, run as a service |
| Fleet setup | Turn several Macs (a shelf of Mac minis) into one cluster, step by step; written so an AI agent can follow it too |
| Runtimes | Linux, macOS and native pods: how each works and when to use it |
| Kubernetes features | What works today, and the known limits |
| Operations | Flags, files, snapshots, upgrades and uninstalling |
| Automated upgrades | Roll a new kvz release across the cluster with k3s-style Plans |
| Architecture | How kvz embeds Kubernetes on macOS |
| Benchmarks | Every result, per machine, with the method |
| Optimization report | How Linux pods went from 12 s to 0.25 s |
| Contributing | Building, testing and sending changes |
| Releasing | Version numbers, CI and how releases ship |
kvz is young. It passes all 454 tests of the Kubernetes certified-conformance suite (Sonobuoy, Kubernetes v1.37.2, two nodes) and runs real workloads (Deployments, StatefulSets, Jobs, Services, Ingress, volumes, hostNetwork, resource limits, HA control planes), but nobody has run it in production yet, so please don't run production on it yet.
Found a security problem? Please report it privately, as described in SECURITY.md. The brand assets (logos, banners, social images) are in docs/assets/brand-v1.
kvz is licensed under the Apache License 2.0. Vendored code in
third_party/ keeps its own license (Apache 2.0 or MIT), in each directory.