Quickstart
Bring up a single-node k3sm cluster on your Mac and run your first native Pod. This is the fastest path; Install explains what happens underneath.
Requirements: Apple Silicon (arm64), macOS 26+. k3sm runs Pods as native Darwin processes; see Concepts.
1. Install#
curl -fsSL https://k3sm.io/install.sh | shThe script checks that this is an Apple silicon Mac on macOS 26+, downloads the release tarball and
its checksums from GitHub Releases, verifies the sha256, prints exactly what it is about to do, and
then runs sudo k3sm install. It installs the newest published release. To pin a particular one (the example names the release you are on today, so change it to the
version you want), put the variable after
the pipe so it reaches sh:
curl -fsSL https://k3sm.io/install.sh | K3SM_INSTALL_VERSION=v0.2.3 shSet K3SM_INSTALL_DOWNLOAD_ONLY=1 the same way to download and verify into the current directory
without running anything as root.
Two alternatives:
- The k3sm app, a signed, notarized download from k3sm.io. See Installing From k3sm.app.
- From source, if you would rather build it yourself: clone
apis,runtimed,darwin-netandk3smside by side, rungo work init ./apis ./runtimed ./darwin-net ./k3sm, build withCGO_ENABLED=1 go build -o k3sm ./cmd/k3sminsidek3sm, assemble the install set withhack/release/stage.sh ../stage, then runsudo ../stage/k3sm install. The staging script needs the Command Line Tools, a signed-inghand the Go release it pins. The full steps are in the repository README.
The one-time admin step (sudo k3sm install, which the script runs for you after printing what it
is about to do) creates the unprivileged _k3sm user, installs the LaunchDaemons, and writes an
admin kubeconfig to your home directory. After that, day-to-day use needs no sudo. See
Install for the install-channel generations and the script’s options.
2. Confirm the Cluster Is Up#
Do not run k3sm server yourself. The install step registered the io.k3sm.server LaunchDaemon
with RunAtLoad and KeepAlive, so the control plane and the node are already running and will
come back after a reboot. A second, foreground k3sm server would contend with it for the work
directory and the apiserver port.
k3sm status # one screen: daemons, apiserver, node, workloads, data root
kubectl get nodes # one Ready darwin nodeIn that output, the install row of k3sm status names the two LaunchDaemons. They are what makes
the cluster survive a reboot, and k3sm status is how you check they came back. Its exit code is the verdict, so a script can branch
on it; k3sm status --help lists the codes.
Install merged an admin context into your ~/.kube/config, so your own kubectl reaches the cluster
with no further setup. See kubectl access for the details, and
Install for what the daemons do.
Running a foreground cluster instead (no daemons, for a throwaway experiment)? Then skip step 1 entirely and run
k3sm serverin a terminal. Never run both.
3. Run a Native Binary as a Pod#
k3sm workloads are native Darwin executables, not OCI Linux images; see Images.
The image: native sentinel runs an absolute host binary as a confined pod. Every k3sm Pod must
declare the darwin node selector and tolerate the node’s provider taint, so use a manifest rather
than kubectl run:
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: hello
spec:
nodeSelector:
kubernetes.io/os: darwin
tolerations:
- key: k3sm.io/provider
operator: Exists
effect: NoSchedule
restartPolicy: Never
containers:
- name: hello
image: native
command: ["/usr/bin/sw_vers"]
EOF
kubectl get pods
kubectl logs helloDrop the nodeSelector and the cluster rejects the Pod at admission. That guardrail keeps
Linux-assuming workloads off these nodes. examples/hello-native.yaml in the repo is the same shape.
For your own workload, build a darwin/arm64 binary with your normal toolchain and point
command[0] at its absolute path (or set image: /abs/path with no command).
Before You Go Further#
k3sm is not a drop-in Linux Kubernetes. Before building anything you depend on, read
Limitations, especially the notes on DNS, restartPolicy per runtime path, and
the resource model.
Next#
- Install covers the install model and the
_k3smposture. - Concepts explains how Kubernetes maps onto Darwin processes.
- Troubleshooting helps when something does not come up.