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.ZatHEAD: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:
- Ubuntu node template
- Lima provisioning
- Seed builder
- macOS finalizer
- Artifact template renderer
- GitLab pipeline
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.
- Shared guest provisioning
- Kernel builder
- Rootfs builder
- Unified manifest renderer
- Linux prerequisites and artifact resolver
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.