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

#Contributor and artifact tooling

Everything here is source-checkout maintainer tooling, not a prerequisite for installed binary users. For ordinary preparation/startup use the product flow. Do not run builds, probes or benchmarks without authorization. CI is the default; macOS build/image/cache/large temporary output must use a configured mounted external build volume, never internal SSD fallback. Runtime cluster disks may use local SSD.

All repository links below are pinned GitHub source references at eb21785.

#Contributor harness examples

Sample E2E projects are in examples/:

cargo run -- test ls --project-root examples/harness/nginx-smoke
cargo run -- test ls --project-root examples/harness/job-smoke

#Build versioning

cargo build generates the version used by kalisto --version and MCP serverInfo.version:

  • Exact clean release tag vX.Y.Z at HEAD: X.Y.Z.
  • Off-tag/dirty with nearest matching release tag vX.Y.Z: X.Y.(Z+1)-dev.<commits_since_vX.Y.Z>+g<short_sha>[.dirty].
  • No matching release tag: <Cargo.toml version>-dev.<commit_count>+g<short_sha>[.dirty].

Examples:

clean tag v1.4.2:                 1.4.2
7 commits after v1.4.2:           1.4.3-dev.7+gabc1234def56
same commit with tracked edits:  1.4.3-dev.7+gabc1234def56.dirty

Override explicitly for CI/local builds:

KALISTO_BUILD_VERSION=1.4.3-rc.1+build42 cargo build

These version examples are not claims that corresponding releases exist. Current downloadable candidates are described in binary releases.

#Legacy Lima image helpers

The optional Lima backend's normal kalisto pull already prepares a sanitized compressed Ubuntu raw disk through native VZ without starting Kubernetes. It does not need these scripts or host QEMU. Lima YAML templates are Lima-only; Apple-container startup neither needs nor consumes a disk-image template.

The separate legacy two-stage flow builds a Linux-container seed via maintainer scripts/GitLab configuration, then boots/finalizes it under Lima on macOS and exports an OS disk.

Relevant files:

Build seed, then finalize:

./scripts/macos/build_lima_node_image.sh
sh scripts/macos/finalize_lima_node_image.sh

macOS finalization requires limactl, qemu-img, and sha256sum or shasum. If QEMU is absent, install it before this legacy script, for example:

brew install qemu

Default outputs:

artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64.qcow2
artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64.yaml
artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64.manifest
artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.qcow2
artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.yaml
artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.manifest

The seed builder produces the seed disk/manifest. Finalization boots it once under Lima, waits for the Kalisto node-image marker and working k3s binary, then uses qemu-img to export compact finalized qcow2, template and manifest. This differs from native pull's compressed raw export.

#Optional prebuilt Lima image publication

For this legacy publishing flow the minimum required runtime artifact is:

artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.qcow2

Recommended companions are the -finalized.manifest and -finalized.yaml; intermediate seed .qcow2, .yaml, .manifest are optional. Kalisto can render a matching template locally from the finalized image. Build/finalize with the two commands above; this workflow is not native managed preparation.

Install an existing artifact into the managed XDG cache locally:

mkdir -p ~/.local/share/kalisto/artifacts/node-image
cp artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.qcow2 \
  ~/.local/share/kalisto/artifacts/node-image/
sh scripts/macos/render_lima_artifact_template.sh \
  ~/.local/share/kalisto/artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.qcow2 \
  ~/.local/share/kalisto/artifacts/node-image/ubuntu-24.04-minimal-k3s-arm64-finalized.yaml

Kalisto looks first under ~/.local/share/kalisto/artifacts/node-image/. With an explicitly published stable source, configure fetch-on-cache-miss inputs:

export KALISTO_LIMA_IMAGE_URL="<published-url>/ubuntu-24.04-minimal-k3s-arm64-finalized.qcow2"
export KALISTO_LIMA_IMAGE_SHA256="<sha256>"

KALISTO_LIMA_IMAGE_FILENAME overrides the default finalized filename when needed. These placeholders do not assert a published image exists and do not relax the no-download-during-up contract; prepare matching local assets before startup.

#Firecracker artifact pipeline

Linux builders reuse the shared Ubuntu guest provisioning recipe but emit Firecracker-specific kernel/rootfs, not Lima templates. They are maintainer tools, never steps run by kalisto up.

On an authorized Linux build host:

./scripts/linux/build_firecracker_kernel.sh
./scripts/linux/build_firecracker_rootfs.sh
./scripts/linux/render_firecracker_artifact_manifest.sh

Scripts detect the installed Firecracker version and host architecture. For v1.18.x on x86_64, outputs are:

artifacts/firecracker-node/v1.18/x86_64/kalisto-vmlinux
artifacts/firecracker-node/v1.18/x86_64/kalisto-vmlinux.config
artifacts/firecracker-node/v1.18/x86_64/kalisto-vmlinux.manifest
artifacts/firecracker-node/v1.18/x86_64/ubuntu-24.04-minimal-k3s-amd64-rootfs.raw
artifacts/firecracker-node/v1.18/x86_64/ubuntu-24.04-minimal-k3s-amd64-rootfs.manifest
artifacts/firecracker-node/v1.18/x86_64/firecracker-artifacts.manifest

The GitLab pipeline defines a combined publish:firecracker-artifacts job artifact set. A configured project's latest-artifact endpoint can address a manifest using:

<project-url>/-/jobs/artifacts/<ref>/raw/artifacts/firecracker-node/<major.minor>/<arch>/firecracker-artifacts.manifest?job=publish:firecracker-artifacts

This is an endpoint pattern, not an implicit public artifact source or publication claim. Supply actual trusted sources explicitly. Firecracker resolution documents all KALISTO_FIRECRACKER_* source/checksum/cache overrides and the restriction to the managed set's baked K3s version. Rootless networking prerequisites must be installed before preparation/startup.

#Lima substrate probe

cargo run -- probe-macos-lima --workspace-root .

Overrides:

cargo run -- probe-macos-lima \
  --workspace-root . \
  --template /absolute/path/to/custom-node.yaml \
  --network vzNAT

Validates limactl reachability, Lima startup with vmType=vz, writable workspace mount visibility, cgroup/overlayfs visibility and Rosetta/binfmt visibility when enabled. This intentionally writable probe mount is not the product Apple backend's narrow-mount contract.

#Lima k3s probe

cargo run -- probe-macos-lima-k3s --workspace-root .

Agentless control plane:

cargo run -- probe-macos-lima-k3s \
  --workspace-root . \
  --agentless

Minimal multi-node:

cargo run -- probe-macos-lima-k3s \
  --workspace-root . \
  --template /absolute/path/to/custom-node.yaml \
  --workers 1

These legacy probes have a different baseline from prepared product startup. Their defaults disable traefik, servicelb, metrics-server, local-storage and embedded network policy; they retain containerd, kube-proxy, CoreDNS and Flannel. Prepared kalisto up instead defaults to no CNI, requiring explicit Cilium selection for networking. Do not transfer probe assumptions to product setup.

See authorized opt-in live tests for KALISTO_LIVE_LIMA_TESTS, KALISTO_LIVE_LIMA_K3S_TESTS and KALISTO_LIMA_K3S_WORKERS; full startup acceptance is stronger than these substrate checks.