Run the full Okteto platform natively on your Mac with KIAC

Community Spotlight
1

Get the full Okteto self-hosted platform running right on your Apple silicon Mac - natively, on Apple’s container runtime, with no cloud, no credit card, and no Docker Desktop. You’ll use kiac (“Kubernetes in Apple Containers”) to stand up a real cluster where every node is its own lightweight VM, install Okteto with a free license, and deploy a live multi-service app you can open in your browser.

What is kiac?

kiac - “Kubernetes in Apple Containers” - spins up a real Kubernetes cluster on macOS using Apple’s container framework. Instead of nodes sharing one kernel like most local-Kubernetes tools, every node is its own lightweight VM with a real kernel, cgroups, and IP address. It comes with the essentials already wired in - metrics-server, a default storage class, and a LoadBalancer - so what you get is a fast, disposable, production-like cluster running entirely on your laptop. No Docker Desktop, no cloud.

kiac is built by Saiyam Pathak - CNCF Ambassador, founder of Kubesimplify, and KubeCon co-chair - one of the most recognized educators in cloud native and AI infrastructure, and a good friend of Okteto. If you want to go deeper on kiac itself, star the repo and follow Saiyam’s work.

What you’ll end up with

  • A single-node Kubernetes cluster running locally in Apple VMs
  • The Okteto platform (dashboard + build service + registry) running on it
  • The oktetodo todo-list app (React frontend + Node API + database) deployed through the Okteto CLI
  • A public-style HTTPS URL for the app, served from your laptop

Time: ~20 minutes, most of it waiting on downloads.

Prerequisites

  • Apple silicon Mac (M1 or later)
  • macOS 26 (Tahoe) or newer recommended. macOS 15 works for a single node with limitations.
  • ~6 GB of free RAM for the cluster VM
  • Homebrew installed

That’s it. You do not need Docker, a cloud provider, or an existing Kubernetes cluster. It runs fine alongside Docker Desktop if you have it - they’re independent stacks.

Step 1 - Install Apple’s container runtime

kiac builds on apple/container, Apple’s open-source container runtime that runs each workload in its own VM.

  1. Download the latest signed installer (.pkg) from the releases page (1.1.0 or newer).
  2. Double-click it and follow the installer (enter your password when prompted).
  3. Start the runtime and install the default Linux kernel:
container system start
container system kernel set --recommended
  1. Verify it can boot a VM:
container run --rm docker.io/library/alpine:3.20 uname -a
# → Linux ... aarch64 ...

If you see a Linux kernel line, the runtime works.

Step 2 - Install kiac

brew install saiyam1814/tap/kiac
kiac doctor

kiac doctor should report all green:

 ✓ macOS version
 ✓ apple/container CLI
 ✓ container system service running
 ✓ kubectl
 ✓ Apple silicon arm64
  all good - run: kiac create cluster

kiac doctor needs kubectl. If you don’t have it: brew install kubernetes-cli.

Step 3 - Create a local Kubernetes cluster

kiac create cluster --name okteto --workers 0 --k8s-version 1.35 --cpus 4 --cp-memory 6G
  • --workers 0 makes a single untainted node, so every Okteto pod schedules on it (lean for a laptop).
  • --k8s-version 1.35 keeps you inside Okteto 1.46’s officially supported range (1.33-1.35).
  • kiac automatically installs a LoadBalancer (kiac-lb), a default StorageClass, and metrics-server.

Confirm the node is Ready and grab its IP - you’ll use it for the domain:

kubectl --context kiac-okteto get nodes -o wide
# NAME                       STATUS   ROLES           ...   INTERNAL-IP
# kiac-okteto-control-plane  Ready    control-plane   ...   192.168.64.3

Note the INTERNAL-IP (e.g. 192.168.64.3). We’ll turn it into a wildcard domain with nip.io: 192.168.64.3.nip.io resolves *.192.168.64.3.nip.io straight to that IP - no DNS setup needed.

Running more than one node? kiac routes all type: LoadBalancer traffic (including Okteto’s ingress) through a single node it labels kiac.io/lb-primary=true. Use that node’s IP for the domain, not just any node’s:

kubectl --context kiac-okteto get nodes -l kiac.io/lb-primary=true -o wide

With --workers 0 there’s only one node, so it’s the same IP either way.

Step 4 - Get a free Okteto license

Okteto self-hosted is free for up to 5 users with no license at all, and offers a free trial for up to 100 users for a month.

To get a trial license key:

  1. Go to okteto.com/signup and fill out the Self-Hosted Free Tier form.
  2. A license key is emailed to you automatically - no sales call required.

Keep the key handy for the next step. (See the license docs for details.)

Step 5 - Install Okteto with Helm

Add the chart repo:

helm repo add okteto https://charts.okteto.com
helm repo update

Create a values.yaml. Replace the license with yours and the IP with your node’s IP from Step 3. The replicaCount/replicas overrides pin every component to a single replica - ideal for a laptop trial.

# values.yaml
license: "PASTE-YOUR-LICENSE-KEY-HERE"
subdomain: "192.168.64.3.nip.io"   # <node-ip>.nip.io

# One replica per component (laptop-friendly)
api:
  replicaCount: 1
webhook:
  replicaCount: 1
frontend:
  replicaCount: 1
buildkit:
  replicaCount: 1
  hpa:
    adapter:
      replicaCount: 1
registry:
  replicaCount: 1
autoscaler:
  replicaCount: 1
sshAgent:
  replicaCount: 1
defaultBackend:
  replicaCount: 1
privateEndpoints:
  replicaCount: 1
regcredsManager:
  replicas: 1
ingress-nginx:
  controller:
    replicaCount: 1
okteto-nginx:
  controller:
    replicaCount: 1

This is the full Okteto platform - every feature is available. Single replicas don’t strip anything out; they just scale each component down to fit a laptop. That makes it a great way to try the complete product quickly.

Install and watch the pods come up (2-4 minutes on first pull):

helm install okteto okteto/okteto -n okteto --create-namespace -f values.yaml
kubectl -n okteto get pods -w

When everything is Running, confirm the ingress got your node IP, then reprint the dashboard URL and admin token from the install notes:

kubectl -n okteto get svc okteto-ingress-nginx-controller
# EXTERNAL-IP should equal your node IP
helm get notes okteto -n okteto

Open the dashboard URL (https://okteto.<node-ip>.nip.io) and accept the self-signed certificate to confirm the platform is live.

Step 6 - Log in with the Okteto CLI

Install the CLI:

brew install okteto

You need the admin token, which Okteto prints in the Helm install notes from Step 5. Reprint them any time:

helm get notes okteto -n okteto

The notes contain both the dashboard URL and a ready-to-run login command - copy the --token value from there:

Access your Okteto instance at https://okteto.192.168.64.3.nip.io/login#token=<TOKEN>

  okteto context use https://okteto.192.168.64.3.nip.io --token <TOKEN> --insecure-skip-tls-verify

Run it, then confirm the context is active with a buildkit builder and a registry URL:

okteto context use https://okteto.192.168.64.3.nip.io \
  --token <TOKEN> \
  --insecure-skip-tls-verify

okteto context list

Step 7 - Deploy the oktetodo app

Clone the sample app and deploy it. Okteto reads okteto.yaml, builds the frontend and backend images with the in-cluster build service, pushes them to the in-cluster registry, and installs the three Helm charts (db, server, client).

git clone https://github.com/okteto/oktetodo
cd oktetodo
okteto deploy

The okteto.yaml in the repo does this:

build:
  server:
    context: server
  client:
    context: client
deploy:
  - name: Deploy the DB
    command: helm upgrade --install db db/chart
  - name: Deploy the Node.js Backend
    command: helm upgrade --install server server/chart --set image=${OKTETO_BUILD_SERVER_IMAGE}
  - name: Deploy the React Frontend
    command: helm upgrade --install client client/chart --set image=${OKTETO_BUILD_CLIENT_IMAGE}

Step 8 - Open the app

The app’s ingress is annotated with dev.okteto.com/generate-host: "true", so Okteto assigns it a public HTTPS host automatically. That single endpoint serves the React todo UI at / and the API at /todos.

Get the generated URL:

okteto endpoints

Then open it in your browser - you’ll get the todo list app, running end-to-end on your Mac. You can also hit the API directly:

curl -k https://<generated-host>/todos

Clean up

When you’re done, tear everything down:

kiac delete cluster --name okteto

To also stop the Apple runtime: container system stop.

Why this is nice

  • Zero cloud. The whole platform - build service, registry, dashboard, ingress - runs in Apple VMs on your laptop.
  • Real Kubernetes. kiac uses upstream kubeadm node images, so it behaves like a production cluster, not a toy.
  • Free. No license needed for up to 5 users; the trial covers more.
  • Disposable. One command to create, one to delete.

Keep going - Okteto is free for your team

You just ran the complete Okteto platform on your laptop. The same platform is free for up to 5 users, with no license - so you can keep using it for real work: give everyone production-like environments, spin up a preview for every pull request, and put dev, build, and deploy behind one CLI.

Built something with kiac + Okteto? Share it back with the community - we’d love to see it.

1 Like