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

#CLI and cluster lifecycle

Use the installed binary from any directory; a checkout and cargo run are not required. Inspect existing resources before creating, reusing, stopping or deleting them.

#Product command reference

kalisto pull --addons cni/cilium
kalisto up --workers 2 --addons cni/cilium
kalisto ls
kalisto --json ls
kalisto apply --name kalisto --manifest app.yaml
kalisto kubectl --name kalisto -- get nodes
kalisto status --name kalisto
kalisto kubeconfig --name kalisto
kalisto down --name kalisto
kalisto up --name kalisto
kalisto scale --name kalisto --workers 3
kalisto destroy --name kalisto
kalisto bench --runs 3 --workers 2 --addons cni/cilium

Treat this as a command reference, not an instruction to destroy a cluster or run a benchmark. scale --workers 3 requests three workers (plus the server), not three total nodes. Scale syntax is defined in the pinned CLI source.

down stops VMs but retains disks/state; installed workloads and VM-local data survive stop/resume. up resumes the saved backend/profile, including Firecracker artifact choices and SSH identities. Failed startup preserves definitions/disks: inspect status/logs and resume, rather than automatically deleting valuable state.

destroy irreversibly deletes the named cluster's state/disks. destroy --all / destroy -a delete all saved clusters and require explicitly authorized full cleanup. Prepared artifacts remain cached. Never infer deletion permission from a failed startup or port collision.

#Names, project configuration and ports

kalisto up \
  --addons cni/cilium \
  --project-root . \
  --workers 0 \
  --api-port 16443

--workers 0 starts a server-only profile. Use --backend or [cluster] backend = "lima" in kalisto.toml to select an alternative explicitly. Existing clusters retain their recorded backend; changing selection does not convert disks.

Agents/shared hosts should always pass explicit names and the matching kubeconfig instead of relying on mutable global selection. Concurrent clusters need different names and free --api-port values; the default API port is 16443. A distinct name alone does not avoid that conflict.

#Managed kubectl and manifests

kalisto apply --name kalisto --manifest app.yaml sends a user-supplied manifest to a running cluster. kalisto kubectl --name kalisto -- get nodes runs checksum-verified managed kubectl matching the cluster's Kubernetes/K3s version against its kubeconfig. pull prepares the binary; otherwise it can be fetched on first use, not during up. The standalone host kubectl command is not added to PATH.

With your own host client:

export KUBECONFIG="$(kalisto kubeconfig --name kalisto --path)"
kubectl get nodes
kubectl -n kube-system get pods
kubectl apply -f app.yaml

New application images may need registry access after startup. See workloads and explicit add-ons.

#Machine-readable inspection

Human-readable output is the default. The global --json flag emits machine-readable JSON for read-only list (ls), status, stats without --watch, and kubeconfig. Treat JSON field names as stable; non-JSON text is a convenience format, not an API.

#Progress and logs

Development source now uses indicatif progress bars and spinners for interactive preparation, cluster startup, worker joins, add-on rollout, manifest application and scaling. Item counts advance only after successful work; waits with no known total use a spinner, not an invented percentage. Applying a manifest does not claim that its workloads are Ready.

Progress uses stderr and keeps warnings and errors visible. Pipes, JSON inspection, CI and TERM=dumb use plain diagnostic output instead of animation. NO_COLOR removes colour. Explicit --log-level or RUST_LOG selection keeps ordinary logs; raw streamed runtime output and live k3s bootstrap logs require debug. The downloadable candidate and recordings are versioned separately; check their source revision before expecting development-source UI changes.

To inspect full diagnostics:

RUST_LOG=debug kalisto up --addons cni/cilium
RUST_LOG=warn kalisto bench --runs 3 --workers 2 --addons cni/cilium

The optional benchmark runs real lifecycle paths repeatedly and prints per-run timings. It is not equivalent to the functional three-node budget test, which checks authenticated API, all Cilium rollouts and both-worker DNS/cross-node traffic. Do not run benchmarks/live validation without the required explicit authorization.

#User-scoped files

config: ~/.config/kalisto
state:  ~/.local/share/kalisto/clusters/<name>/

Reusable profiles live under artifacts/boot-v4 in Kalisto data; optional Lima disks/templates use artifacts/node-image, and Firecracker has its own versioned artifact cache. Private kubeconfigs/tokens/TLS manifests are not safe to publish.

#Troubleshooting without destructive fixes

  • A missing/incompatible prepared profile means rerun pull with matching backend, architecture, K3s/Cilium versions and add-ons. Do not delete locks/caches automatically or expect online startup recovery.
  • No pod networking after bare up is consistent with the no-CNI default; Cilium must be selected in both preparation and startup. Existing Helm-managed Cilium is not migrated in place.
  • An incompatible shared Apple daemon must not be stopped, replaced or reconfigured by Kalisto; use Lima explicitly or separately coordinate maintenance.
  • For Apple helper connectivity after an upgrade, approve only required firewall helpers, not a disabled firewall.
  • Check API port availability as well as cluster names before retrying.