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]
local_max_size = "50GiB"
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%.

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

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.

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.