Eval cache behavior

Kix keeps the results of cluster evaluations in local files so that repeated commands against an unchanged flake skip evaluation. A cached result is reused only when the flake’s source files and flake.lock are unchanged.

This page is hand-maintained. Check cli/kix-core/src/eval/cache.rs, cli/kix-core/src/eval/evaluator.rs, and cli/kix-core/src/eval/store.rs when in doubt.

Location

Path	Content
<cache dir>/kix/eval-cache	Evaluation results and source fingerprints, one file each
<cache dir>/kix/store	Kix’s local store for the default kix builder (flake inputs, rendered Helm charts, and evaluated manifests), or $KIX_STORE_ROOT when set; projects with builder = "nix" in kix.toml use /nix/store instead
<cache dir>/kix/activations/<cluster>	Symlinks and paths for each cluster’s last local activation

<cache dir> is $XDG_CACHE_HOME when set, or ~/.cache on both Linux and macOS. Deleting eval-cache is safe. The next command re-creates it and evaluates the cluster again.

Kix keeps one result for each project and each thing it evaluates, such as a cluster. A new result replaces the old one, so the cache does not grow as you edit. Switching back to a branch you used before evaluates its clusters again.

What is cached

Entry	Used by
A cluster’s evaluation: rendered manifests and the scorecard report	build, check, graph, inspect, images, status, compliance audit
The flake’s cluster names	list clusters, and the “did you mean” list when a cluster is not found
Available packages, and a cluster’s instances	list packages

Commands that evaluate the cluster’s activation index directly, such as deploy, plan, diff, bundle, export, logs, and pf, do not read the eval cache. They evaluate the cluster each time. The store (<cache dir>/kix/store under the default kix builder, or /nix/store under builder = "nix") keeps the project’s inputs and rendered Helm charts, so these are not fetched or rendered again.

Cache key

Each entry’s key is a BLAKE3 hash of:

1. the canonical path of the flake directory;
2. the contents of flake.lock, when it exists;
3. a fingerprint of the flake’s source files;
4. the name of what was evaluated, such as the cluster name;
5. the project’s builder (kix or nix, from kix.toml);
6. the store location (the local store root path for kix, or the system store marker for nix).

The source fingerprint hashes the path and contents of every .nix, .yaml, .yml, and .json file under the flake directory, skipping .git, .direnv, result, and node_modules directories. When no file’s modification time has changed since the last run, the stored fingerprint is reused without reading the files.

What invalidates an entry

• Adding, removing, or editing a .nix, .yaml, .yml, or .json file under the flake directory.
• Any change to flake.lock, such as kix lib update.
• Changing builder in kix.toml or changing KIX_STORE_ROOT.
• Running from a different flake directory.

Kix does not use the cache when you pass --override-input, because the key cannot tell what an overridden input holds.

The key does not cover:

• files with other extensions that the cluster reads, for example with builtins.readFile;
• inputs whose content changes without a change to flake.lock, such as a path: input pointing outside the flake directory.

Pass --no-cache after changing any of these. It evaluates from source and neither reads nor writes the cache.

A cache entry that cannot be parsed is discarded and the evaluation runs again. A failure to write the cache is logged and does not fail the command.

Remote flake references

The commands that use this cache need a local directory. They fail when --flake names a remote reference such as github:org/repo, with or without --no-cache. Clone the repository and pass its local path.

Reference

See Global flags for --flake, --no-cache, and --override-input.