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

#Preparation and offline boot

kalisto pull prepares only the selected backend. Apple containers are the macOS default; Firecracker is the Linux default. Use --backend or cluster.backend for an explicit alternative. CLI and MCP pull results identify the selected backend and prepared profile; Firecracker also reports the resolved kernel/rootfs. Only Lima logs a disk-template path.

#Backend-specific assets

Backend Preparation command Backend assets
Apple containers kalisto pull Linux kernel/init and Ubuntu/k3s OCI node image, using the installed Apple runtime; no Lima disk/template
Lima kalisto pull --backend lima Managed Lima runtime and VM disk/template under artifacts/node-image; no Apple runtime/node image
Firecracker kalisto pull --backend firecracker Configured/discovered kernel/rootfs, managed Linux tools and a read-only offline boot-asset disk; no Apple/Lima runtime

All backends cache Kubernetes boot images and matching managed kubectl. Add --addons cni/cilium to prepare Cilium images, its chart and managed Helm, then select the same add-on during up:

kalisto pull --addons cni/cilium
kalisto up --workers 2 --addons cni/cilium

For Lima, add --backend lima to both commands. Firecracker requires its host tools and artifact inputs. There is still no implicit public Firecracker kernel/rootfs source.

#Reusable artifact profiles

Preparation is keyed by architecture, K3s/Cilium versions and enabled components, not by working directory or cluster name. Cache is stored under artifacts/boot-v4 in user-scoped Kalisto data. A complete matching cache is verified/reused rather than rebuilding the OS image. Rerun pull when the profile changes, cache is removed or an Apple runtime image has been pruned.

Preparation may take several minutes and is outside the cold-start clock. It never starts Kubernetes or precreates benchmark VMs/cluster state. Managed Crane downloads platform-digest-pinned OCI images, including BusyBox diagnostics. For Apple, a temporary ordinary container installs the reusable Ubuntu/k3s image prerequisites and is deleted afterward; no cluster identity is baked into it. Kernel extraction runs in Rust, without a host zstd executable. No checkout, manual templates, Docker, host QEMU installation, sudo or Lima is needed for the default Apple path once its runtime prerequisite is ready.

Apple cached node OCI archives are served directly over temporary loopback HTTP on import, without extracting a second archive copy or reconfiguring the shared image helper. Repeating pull can restore a pruned runtime image store. Compatible shared Apple services are borrowed, never replaced; runtime ownership rules also apply during preparation.

#Offline startup contract

up requires complete local assets. It does not install host tools, fetch missing images, download remote Firecracker manifests/kernel/rootfs, or silently change the CNI. Missing preparation tells you to run pull; it is not an online fallback.

Fresh VMs mount boot assets read-only and import images locally. Firecracker shares firecracker-assets.ext4, containing the selected K3s binary and OCI boot archive. Fresh VM creation, image import and CNI startup remain inside the startup clock. Apple nodes start concurrently on an owned NAT network, mounting only their runtime directory and read-only assets, not your home directory, SSH agent or a global shared image store. Workload registry access remains available after startup.

#CNI and supported startup components

The default CNI is none. Explicitly select Cilium in both pull and up for pod networking and CoreDNS. Prepared profiles support all three backends, no CNI or Cilium, and optional lb/servicelb only. Other startup add-ons are rejected rather than silently downloaded. Install ingress, MetalLB and other components explicitly after startup; these online operations are outside the prepared boot budget.

Cilium is rendered locally from the cached Helm chart during up, without Helm download jobs. Generated Hubble TLS keys are unique per cluster, never shared cache contents. The private manifest is mode 0600 in the cluster runtime directory and is reused on resume; Firecracker transfers it privately via SSH/SCP into guests rather than baking it into the shared disk. All rendered DaemonSets and Deployments must roll out. Cilium uses embedded Envoy with L7 policy support, not a separate Envoy DaemonSet.

Existing Helm-managed Cilium clusters require migration: prepared startup targets fresh clusters and rejects the legacy manifest rather than mixing installation methods. Use a fresh cluster name and back up valuable workloads/data before any explicitly authorized destruction. Existing node disks are not converted in place by a new preparation profile or backend choice.

#MCP preparation

clusters.pull uses the lifecycle arguments of clusters.up. It is a task-required mutation; task acceptance is not completion. Wait for a successful terminal result before clusters.up with the same profile. See the MCP task contract.