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

#Linux Firecracker

Firecracker is the Linux default, separate from macOS Apple containers and optional Lima. Prepared offline Cilium startup with rootless networking has been validated on Fedora Linux 44, x86_64, Firecracker 1.18.0 with accessible /dev/kvm. Package builds for other architectures are not equivalent runtime proof.

#Host requirements

Install these before preparation/startup:

  • x86_64 Linux with firmware virtualization enabled, CPU virtualization exposed, KVM modules loaded and permission to open /dev/kvm.
  • Firecracker runnable from PATH.
  • debugfs for NoCloud seed injection and mke2fs for the shared boot-asset disk.
  • OpenSSH ssh, ssh-keygen, scp for guest bootstrap and per-cluster transfers.
  • ip, iptables, sysctl. The current host availability check requires the latter two even in rootless mode; bridge mode uses them for host rules.
  • slirp4netns, unshare, nsenter for rootless networking, including permission to create user/network namespaces.
  • curl for host API readiness; nc for Unix-socket/port checks and jq for JSON inspection/debugging when needed.
  • Permission to create Unix sockets, runtime files and logs in Kalisto workspace/state roots. Bridge networking additionally needs host networking privileges to manage devices/rules.

The validated Firecracker 1.18.0 executable was checksum-verified on 2026-11-16. A user-scoped binary on PATH can take precedence over a distribution package; do not replace a system-managed installation without authorization. The host inspection script can capture prerequisite evidence:

./scripts/linux/inspect_firecracker_env.sh

#Guest artifacts and offline startup

Provide a Firecracker-compatible Linux kernel and a writable raw ext4 rootfs with NoCloud/cloud-init and OpenSSH guest support. A qcow2 image, partitioned cloud disk or Lima template is not suitable. The builders reuse the Ubuntu guest recipe, not Lima's runtime artifacts. A stable implicit public kernel/rootfs source is not yet available.

The guest kernel must include built-in CONFIG_NETFILTER_XT_MATCH_STATISTIC=y alongside the features in Kalisto's kernel fragment. Kube-proxy needs this match for Services with multiple endpoints; without it, an added worker can remain NotReady while Cilium cannot reach the Kubernetes Service. Rebuild older kernels with the updated recipe before preparing this profile. This is a guest-kernel requirement, not a host-module installation.

KERNEL=/absolute/path/to/kalisto-vmlinux
ROOTFS=/absolute/path/to/rootfs.raw
kalisto pull --backend firecracker --addons cni/cilium \
  --firecracker-kernel "$KERNEL" --firecracker-rootfs "$ROOTFS"
kalisto up --backend firecracker --name dev --workers 2 --addons cni/cilium \
  --firecracker-kernel "$KERNEL" --firecracker-rootfs "$ROOTFS"
kalisto kubectl --name dev -- get nodes

pull resolves the artifacts, installs managed Linux Crane/Helm and matching kubectl, and prepares digest-pinned K3s/Cilium/diagnostic images. firecracker-assets.ext4 contains the selected K3s binary and OCI boot archive. It creates no cluster state or nodes. No host Docker or manually installed Helm/Crane is required.

up creates fresh VMs with writable per-node rootfs/SSH identities and attaches boot assets read-only. It imports images locally and applies a locally rendered per-cluster Cilium manifest, privately transferred with mode 0600; credentials/TLS keys never enter the shared disk/cache. Missing artifacts/preparation fail before boot, not via an online fallback. Remote manifests and kernel/rootfs downloads are refused during up.

No CNI is selected implicitly. Profiles support no CNI or explicit Cilium and optional ServiceLB; other startup add-ons must be installed later. Existing Helm-managed Cilium manifests are rejected rather than converted in place; use a fresh cluster name and back up valuable data before explicitly authorized destruction.

#Artifact resolution order

kalisto pull --backend firecracker resolves:

  1. Explicit --firecracker-kernel and --firecracker-rootfs paths.
  2. Versioned roots for the detected Firecracker release track and architecture:
    • artifacts/firecracker-node/<major.minor>/<arch>/
    • ~/.local/share/kalisto/artifacts/firecracker-node/<major.minor>/<arch>/
  3. Legacy roots:
    • artifacts/firecracker-node/
    • ~/.local/share/kalisto/artifacts/firecracker-node/
  4. Explicit configured artifact URLs or a Kalisto manifest, fetched on cache miss only during pull.

For Firecracker v1.18.0 on x86_64, the preferred roots use v1.18/x86_64/. Configured remote manifests must already be cached for up. If no usable source is discoverable/configured, startup fails clearly before attempting VM boot.

KALISTO_FIRECRACKER_MANIFEST_URL supplies managed filenames, checksums, URLs and baked K3s version. Explicit KALISTO_FIRECRACKER_KERNEL_URL and KALISTO_FIRECRACKER_ROOTFS_URL can provide overrides. The managed kernel is Kalisto-owned, not discovered from the upstream Firecracker CI bucket. Rootfs must come from a local workspace, a published Kalisto artifact set or explicit paths; there is no implicit public source.

Supported preparation/resolution variables:

KALISTO_FIRECRACKER_MANIFEST_URL
KALISTO_FIRECRACKER_KERNEL_URL
KALISTO_FIRECRACKER_ROOTFS_URL
KALISTO_FIRECRACKER_KERNEL_FILENAME
KALISTO_FIRECRACKER_ROOTFS_FILENAME
KALISTO_FIRECRACKER_KERNEL_SHA256
KALISTO_FIRECRACKER_ROOTFS_SHA256
KALISTO_FIRECRACKER_ARTIFACT_DIR
KALISTO_FIRECRACKER_ARTIFACT_CACHE_DIR
KALISTO_FIRECRACKER_VERSION
KALISTO_FIRECRACKER_ARCH

Auto-managed rootfs resolution only supports the K3s version declared by the managed artifact set. Non-default K3s versions still require an explicit --firecracker-rootfs. Contributor artifact tooling lists builders, output paths and the configured GitLab artifact endpoint pattern.

#Rootless and bridge networking

The default is slirp4netns: Firecracker runs inside an unprivileged user+network namespace with egress and host port forwards supplied by slirp4netns. No host sudo is needed in this mode.

Use --network bridge only when explicitly choosing privileged host bridge/TAP networking; it needs ip, iptables, sysctl and appropriate host privileges/sudo. Do not use Lima network names such as lima:user-v2, Lima template port forwarding or other Lima networking assumptions.

The backend persists its identity/configuration, discovers or accepts boot artifacts, executes guest bootstrap/readiness commands, and reports/cleans owned microVMs. kalisto down --name dev retains node disks and SSH identities. kalisto up --name dev resumes the persisted profile without repeating artifact flags; kalisto destroy --name dev removes that cluster while retaining prepared boot cache.

#Validation

Native Fedora 44 x86_64 measurement Elapsed
Preparation, outside startup clock 40.68s
Fresh three-node startup and complete functional probes 42.95s

The strict startup deadline includes three fresh VMs, image imports, three Ready nodes, authenticated host API, every Cilium rollout, DNS and cross-node Service HTTP from both workers using cached images with imagePullPolicy: Never. Stop/resume retained a ConfigMap and scale-out reached four Ready nodes afterward, outside the clock. These are observed results, not universal hardware guarantees. See opt-in live tests and evidence.