Kalisto/ documentation source (permission required) ↗
On this page

#macOS Apple containers

Apple's lightweight Linux VM runtime is Kalisto's default macOS backend. It requires Apple silicon, macOS 26+, Apple's compatible container CLI on PATH, and its system service already running in your login session. The validated version is 1.7.1. Initial runtime/kernel setup and pull preparation require network access and precede offline startup measurement.

Kalisto owns its k3s server, agents, Cilium, readiness checks and cluster state. It does not use container cluster, container machine, Apple's experimental Kubernetes implementation, kubeadm, kind, Docker or an external registry to bootstrap prepared nodes. Intel/older Macs must explicitly use Lima.

#Install and start the host runtime

For a new Homebrew installation:

brew install container
container system start
container --version
container list

container list must succeed, even with no containers. If a compatible CLI and running service already exist, skip installation/start; do not reinstall or restart them. Homebrew users managing the service with brew services should read the formula's recommended-kernel setup caveat. See the Homebrew formula and Apple requirements/service setup.

Install Kalisto from the download selector, then:

kalisto pull --addons cni/cilium
kalisto up --workers 2 --addons cni/cilium
kalisto kubectl -- get nodes
kalisto down
kalisto up

The installed flow needs no source checkout, manual image templates, host Docker/QEMU, sudo or Lima. pull uses the existing CLI/runtime, prepares the Linux kernel/init, digest-pinned Ubuntu/k3s node image and matching Kubernetes boot assets/tools. It uses a temporary ordinary builder container, deletes it afterward and never creates Kubernetes nodes or cluster state. up requires the completed cache and never installs the engine or downloads missing startup assets. Preparation covers profile reuse and private Cilium manifests.

#Node images and isolation

Fresh nodes use containerd's OverlayFS snapshotter on the pinned Kata kernel, sharing immutable image layers rather than copying Cilium's full root filesystem for every init container. After upgrading from a native-snapshotter build, rerun kalisto pull to prepare the revised image profile before creating a fresh cluster. Existing node disks are not converted in place.

A cached OCI node archive restores a pruned runtime image store when pull is repeated. Imports use temporary loopback HTTP directly from the archive, without a second extracted archive copy or changes to the shared image helper. Managed Crane handles external init/base image downloads; Rust kernel extraction needs no host zstd.

Nodes start concurrently on a Kalisto-owned NAT network. Only their own runtime directory and read-only prepared assets are host-mounted: no home directory, SSH agent or global shared image store is exposed. Registry access for new workloads remains available after startup.

#Shared-service ownership

Apple's service is shared within a macOS login session. A compatible running service is borrowed without stopping, replacing or changing its executable, installation/application roots, configuration, default system properties or existing data. Kalisto owns only its cluster nodes, networks and VM directories, not the daemon or persistent application root. Runtime selection is recorded in per-user Kalisto data separately from shared artifact cache.

An incompatible running service causes a clear error before downloading a replacement. Kalisto never takes it over. Use Lima explicitly instead, or separately coordinate an engine upgrade/restart with every user of existing containers/clusters. Never stop a compatible Homebrew daemon merely to prepare Kalisto.

#Firewalls and upgrades

Application firewalls such as LuLu may require separate allow rules for Homebrew's container-core-images and container-runtime-linux after an upgrade. Rules for Apple-signed copies do not necessarily match Homebrew builds. Approve only the required helpers; do not disable the firewall.

#Validation and limitations

Native CI measured 46.71s for fresh three-node startup with authenticated host API, all Cilium rollouts, both-worker DNS and cross-node Service HTTP using an existing Homebrew 1.7.1 service. Stop/resume preserved Kubernetes state and scaling reached four Ready nodes afterward, outside the startup timer. This is one completed measurement, not a universal hardware guarantee.

The authorized native CI job records CLI/daemon identity, roots, process identity and default system properties before flag-free preparation/startup with system-only PATH, then compares them after preparation, stop/resume, scaling and destruction. It verifies no private installer was fetched/selected; cleanup never stops the borrowed daemon or removes its application root. CI setup may start a stopped installed service, but never replaces a running daemon. See full acceptance and CI-only live commands.

Cold archive export/import is currently Lima-only. Selecting Apple does not convert existing Lima clusters or archives.