Kache resolves settings in this order:

1. environment variable
2. config file
3. built-in default

KACHE_DISABLED, KACHE_CONFIG, KACHE_SOCKET_PATH, logging controls, progress controls, and credentials are operational settings. They do not all have TOML equivalents.

Config file

Open the editor:

kache config

Or edit TOML directly. Kache chooses the first file in this order:

1. KACHE_CONFIG
2. the nearest .kache.toml, walking up from the current directory
3. $XDG_CONFIG_HOME/kache/config.toml or ~/.config/kache/config.toml

The editor covers common fields and preserves advanced tables it does not expose.

[cache]
cache_executables = true

[cache.remote]
type = "s3"
bucket = "my-build-cache"
region = "us-east-1"

Use type = "filesystem" with path = "/mnt/kache" for a shared filesystem remote. Only s3 and filesystem are compiled remote backends.

Core settings

On macOS the default store is ~/Library/Caches/kache; on Linux it is $XDG_CACHE_HOME/kache or ~/.cache/kache; on Windows it is under %LOCALAPPDATA%.

GC and shared build outputs

cache.local_max_size measures blob bytes registered in Kache's store. A Cargo target directory can hardlink or block-clone those blobs. In that case the store name and the build output refer to the same disk blocks.

By default, GC keeps an entry when removing its last store name would reclaim zero bytes. This preserves a usable cache hit. It also means the registered store size can remain above local_max_size until the target output is removed. kache gc reports these entries as unreclaimable and separates store bytes removed from disk bytes reclaimed.

To reclaim the blocks, remove the retaining build output. For known stale targets, preview Kache's machine-local registry before deleting anything:

kache clean --tracked --stale 14d --dry-run
kache clean --tracked --stale 14d --yes

If enforcing the store namespace limit matters more than retaining hits, restore the older policy:

[cache]
gc_evict_shared = true

The equivalent environment setting is KACHE_GC_EVICT_SHARED=1. With this option, GC can drop an entry even though target files still hold all its blocks. The registered store size falls, but disk usage does not. A later build must compile or download that entry again. Explicit purge and repair operations remain unconditional regardless of this setting.

Compiler policy

Bypass rules can only reduce caching:

[cache]
exclude = ["vendor/problematic/**"]
bypass_crates = ["generated_bindings"]
bypass_argv = ["--cfg", "uncacheable_mode"]
bypass_env = ["SPECIAL_BUILD=1"]

Cache-key controls

KACHE_VERIFY is qualification for cache-key changes. Set it to 1 or true to recompile every rustc cache hit into a staging directory and diff those artifacts against the files just restored. Leave it unset (or 0 / false) in ordinary builds: each hit pays a full compile. There is no kache build command for this.

Path and debug-info bytes that differ only as embedded absolute paths are reported as path-debug and do not fail the build. Remaining byte differences are content. In both cases the restored files stay in place so the build continues; the wrapper records the class on the hit event as verify_compare (and in tracing when logging is on).

KACHE_VERIFY_RESTORES still only re-hashes stored blobs before restore. It does not recompile.

Use a key salt when an unobserved toolchain component changes output:

[cache]
key_salt = "sysroot-2026-08"

Keep paths.base_dirs narrow. Normalizing unrelated roots to stable sentinels can make different inputs appear equal.

key_env_vars accepts exact names and trailing-star prefix patterns:

[cache]
key_env_vars = ["BOLTFFI_*"]

Values are hashed exactly and are not written to event logs. A changing value such as a job ID will destroy hit rate.

Hidden compile-time inputs

Some macros read files that rustc does not report. Put kache.toml without a leading dot next to the crate manifest:

extra_inputs = [
  ".sqlx/**/*.json",
  "migrations/**/*.sql",
]

Matches are relative to that crate. Kache folds their paths and contents into its key and adds bounded watches to Cargo dep-info. Invalid or unreadable declarations fail closed.

For a workspace-root input used by a provider package and its direct consumers:

[[workspace.extra_inputs]]
crates = ["query-macros"]
inputs = [".sqlx/**/*.json"]
propagate_to_dependents = true

Workspace rules are accepted only from the .kache.toml beside the active Cargo workspace manifest. After adding a declaration to a target Cargo already considers fresh, rebuild that package once.

Remote settings

Credentials resolve from explicit KACHE_S3_ACCESS_KEY and KACHE_S3_SECRET_KEY, standard AWS variables, the selected AWS profile, web identity, container credentials, then instance credentials.

See S3 setup or filesystem setup.

Prefetch and planner

On a long-lived runner with a warm local store, speculative prefetch may be unnecessary:

[cache]
prefetch_enabled = false

Exact remote lookup and background upload continue to work.

Telemetry

Kache does not push metrics to a collector. It writes OTLP JSON files that Kartero imports from CI artifacts, the same way nightly benches already work.

Two signals, never mixed:

• kache.bench.* — one-shot bench gauges (duration, speedup, verdict) from kache-scenario
• kache.cache.* — cache counters (uploads, prefetch, store size) from kache telemetry write

kache telemetry write ./cache-otlp --scenario bench-firefox --phase warm

That writes metrics.otlp.json and schema_version in the directory. --scenario must match kache.bench.project. --phase distinguishes cold from warm: the bench stops the daemon between phases, so counters are per daemon lifetime. The rustc wrapper does not write these files. The planner service still exposes Prometheus /metrics for cluster scrape.

Daemon, events, and diagnostics

Pin file-backed settings

Set cache.ignore_env in a controlled project config to ignore environment overrides for settings that also exist in TOML:

[cache]
ignore_env = true

It does not suppress KACHE_DISABLED, KACHE_CONFIG, KACHE_SOCKET_PATH, credentials, logging, progress, or other environment-only controls. Kache warns when it ignores a set variable.

The daemon reads configuration at startup and watches the active config file. File changes trigger a graceful restart. Environment changes require starting a new daemon from that environment; an installed service uses its service definition, not your current shell.