Configuration

kache reads configuration from three places, in order of priority:

1. Environment variables — always win, useful for CI overrides
2. Config file — selected from the config file priority below
3. Defaults — sensible values that work without any configuration

Config file

The config file is TOML. You can edit it directly or use the TUI editor:

kache config

The TUI editor surfaces the common fields with their current values, marks which ones are coming from env vars (those are read-only and the cursor skips them), and lets you toggle or edit the rest interactively. Navigate with the arrows or j/k, jump between sections with Tab/Shift-Tab, Enter edits a field, Space toggles a boolean, s (or Ctrl-S) saves, and q/Esc quits with an unsaved-changes prompt. Some advanced sections — [cache.planner], [cc], [paths], cache.path_only_env_vars, and cache.key_env_vars — have no form fields and are preserved verbatim on save.

Config file priority:

1. KACHE_CONFIG, when set
2. The nearest project-local .kache.toml, walking up from the current directory
3. User config at ~/.config/kache/config.toml, respecting XDG_CONFIG_HOME

kache currently compiles two remote types: s3 and filesystem.

[cache.remote]
type = "s3"
bucket = "my-build-cache"
endpoint = "https://s3.example.com"   # omit for AWS S3
profile = "my-aws-profile"            # omit to use the default credential chain

[cache.remote]
type = "filesystem"
path = "/mnt/shared-kache"
prefix = "artifacts"

Other OpenDAL services are not included in the kache binary. Existing S3 configuration names remain compatible: a legacy [cache.remote] table without type = "s3" and an environment-only setup rooted in KACHE_S3_BUCKET still select S3; the other KACHE_S3_* overrides remain available. See the S3 migration boundaries for AWS SDK-specific cases that need attention.

All settings

* In wrapper mode (RUSTC_WRAPPER, the common path) stderr logging defaults to off and the file log is disabled unless KACHE_LOG_FILE is set explicitly. The kache=warn / kache=info defaults apply to CLI and daemon invocations.

Prefetch policy by runner lifetime

Speculative prefetch is designed to hide remote latency on a cold runner by downloading likely artifacts before rustc asks for their exact keys. It is optional: exact-key remote lookup and background uploads use separate daemon paths.

For a long-lived runner with a persistent local store, speculative prefetch can cost more than it saves. The local store is already warm, while fallback planning may have to index a large shared remote and choose among many variants of the same crate name. Disable speculation without disabling the remote cache:

[cache]
prefetch_enabled = false

This mode keeps local hits, exact remote hits, and asynchronous uploads. It skips startup manifest warming, build-start advisory/fallback planning, direct prefetch requests, and remote key-cache population. The daemon watches the config file and restarts when it changes. If you use KACHE_PREFETCH_ENABLED instead, restart the daemon explicitly because an existing daemon cannot see a changed environment.

For cold or ephemeral CI, leave prefetch enabled and use build-shape-specific manifest keys and namespaces. If periodic discovery is useful but a 60-second full listing is too frequent, keep prefetch enabled and raise remote_key_cache_refresh_secs. Raising it reduces LIST frequency, but stale negative entries are authoritative for no more than five minutes; after that, exact misses fall through to a remote HEAD probe. Set the interval to 0 for one startup population with no refresh: positive entries and fallback planning still use that snapshot, while negative entries never suppress exact remote lookup.

Excluding Sources

Use cache.exclude when a source file should compile normally but never use kache:

[cache]
exclude = [
  "crates/problematic-rust-crate/**",
  "vendor/problematic-c-lib/**",
  "$CARGO_HOME/registry/src/**/some-crate-*/**",
]

Patterns are globs matched against the compiler's primary source path. Relative patterns are matched relative to the current build directory and, when kache can infer it, the Cargo workspace root. Excluded invocations bypass local lookup, remote lookup, store, and upload.

Exclude patterns support ~, $VAR, and ${VAR} expansion. $CARGO_HOME falls back to Cargo's default ~/.cargo when the environment variable is not set, so registry-source exclusions work on default Cargo installs.

Pinning config against env

By default every KACHE_* environment variable wins over the config file — convenient for CI overrides, but it means a stray machine-global export can silently change behavior. The riskiest case is KACHE_KEY_SALT: a leaked export would shift every cache key without a word.

Set ignore_env to make a pinned config authoritative:

[cache]
ignore_env = true
key_salt = "v3-toolchain-abc"

With this, kache ignores the KACHE_* overrides for file-backed settings (cache dir, max size, key salt, fallback, remote/planner settings, the toggles, etc.) and takes the file value (or built-in default) instead. When an ignored override is actually set, kache logs a warning naming it, so the suppression is never silent.

ignore_env is file-only by design — an env var can't re-enable env overrides, or the lockdown would be trivially undone by the same stray export it defends against. It deliberately does not cover bootstrap/operational vars that have no file representation (KACHE_CONFIG, KACHE_DISABLED, KACHE_LOG / KACHE_LOG_FILE / KACHE_PROGRESS, KACHE_NAMESPACE, KACHE_BASE_DIR) or S3 credentials (KACHE_S3_ACCESS_KEY / KACHE_S3_SECRET_KEY), which are secrets rather than config.

Cache-key salt

kache's cache key captures everything it can observe about a compile: the rustc version, the target, flags, source and dependency hashes, and the linker's --version banner. Native Linux OS-loaded outputs also key the host GNU libc or musl version, while portable rlibs and cross-target outputs exclude that host-only signal. The observable set is not complete for toolchain changes that leave every reported version unchanged — for example a custom or cross-target libc/sysroot replacement, a distro patch that retains the same upstream libc version, a hidden mold/linker change, or a Nix store rebuild that swaps the ELF interpreter baked into a binary.

When that happens, the key does not move, so a stale artifact can be restored. On Nix in particular, a nixpkgs bump followed by nix store gc can leave a restored executable pointing at a garbage-collected interpreter — an error no cargo clean can fix, because the key never changed.

key_salt is an opaque string folded into every cache key. Set it to a value that does change when your toolchain changes — a hash of the toolchain closure, a store-path digest, a date, a CI build id — and that change re-keys the cache (a cold miss) instead of serving a stale hit:

[cache]
key_salt = "nixpkgs-a1b2c3d-mold-2.40"

Or compute it from the toolchain itself:

export KACHE_KEY_SALT="$(nix eval --raw .#devShells.default.outPath | sha256sum | cut -c1-16)"

The salt is hashed raw; its meaning is entirely yours. An unset or empty value has no effect — keys are byte-identical to not setting it — so it is safe to leave off until you need it. A misconfigured salt can only cost hit rate (an extra miss), never cause a wrong artifact to be restored.

Extra cache-key inputs

kache keys a crate on what the compiler reports — source files, --extern dependencies, flags. Some crates also read files at compile time that the compiler never reports, so kache can't see them change:

• sqlx's query! macro reads .sqlx/query-*.json (the offline query cache)
• migration macros read migrations/
• codegen / macros that include! data files by a path rustc doesn't surface

Edit one of those and the .rs files are unchanged, so the key doesn't move — and kache would restore the previously-compiled artifact (a stale hit). Declare those files so a change to them re-keys the crate.

Add a kache.toml next to the crate's Cargo.toml:

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

Globs are relative to the crate directory. A bare directory is fine — .sqlx and .sqlx/ both mean "everything under it." The matched files' contents are folded into that crate's key.

A pattern may reach outside the crate with .. or an absolute path when a build genuinely depends on a shared tree above the crates or a machine-specific file. That's allowed and stays fail-safe, but it makes the crate's key host- or layout-specific (kache logs a warning), so it no longer shares across machines or worktrees — prefer a co-located input where you can.

This is opt-in and scoped per crate: a crate with no kache.toml is unaffected, and one crate's extra_inputs never implicitly touch a sibling crate's key. It is also union-only — a misdeclared glob can only cause an extra cache miss (a rebuild), never restore a wrong artifact. Each file is folded as its crate-relative path plus content hash, so moving the worktree doesn't bust the cache, but swapping two matched files' contents (where order matters, like sqlx migrations) does re-key. The declared patterns are folded too, so editing kache.toml itself re-keys — even when it currently matches nothing.

Extra path prefixes

Use the file-only [paths].base_dirs list when automatic workspace/home/temp detection and the legacy single KACHE_BASE_DIR do not cover paths baked into artifacts—for example container mounts, /snap, /var/lib/flatpak, an AppImage mount, or a custom toolchain root:

[paths]
base_dirs = ["/snap", "/var/lib/flatpak", "/work"]

Entries must be absolute and contain no ... They need not exist on every machine, so a shared project config remains usable outside the container or sandbox. kache sorts the normalized entries independently of TOML order, assigns each one a distinct <BASE_DIR_N> key sentinel and /kache/base-dir-N compiler path, and uses the longest configured prefix when entries overlap. The configured roots feed both rustc and gcc/clang key inputs and emitted prefix maps. KACHE_BASE_DIR remains supported as the separate legacy <BASE_DIR> rule.

Path-only env vars

By default kache normalizes the absolute path baked into OUT_DIR so the cache key stays portable across machines and worktrees. Some builds set other env vars that serve the same role — they only point at a generated file that a crate include!s, and their absolute value should not bust the key (e.g. Firefox's BUILDCONFIG_RS / MOZ_TOPOBJDIR).

cache.path_only_env_vars opts those vars into the same path-only treatment:

[cache]
path_only_env_vars = ["BUILDCONFIG_RS", "MOZ_TOPOBJDIR"]

Or via the environment (comma- or whitespace-separated; replaces the file list entirely):

export KACHE_PATH_ONLY_ENV_VARS="BUILDCONFIG_RS MOZ_TOPOBJDIR"

This is an advanced opt-in: only list vars whose value is purely a path locator. An empty list means only OUT_DIR is normalized.

Env vars that steer expansion

kache keys the compile-time environment a build bakes in — the env!() and option_env!() values rustc reports in dep-info. A proc macro that calls std::env::var while expanding is a different story: rustc has no way to report it, so the command line, the source hashes, and the --extern set are byte-identical whether or not the var is set, while the emitted artifact is not.

That is a real failure mode, not a hypothetical one. In #635 a two-phase build ran the same crate graph twice — once with BOLTFFI_BINDING_EXPANSION=1, where the #[export] macro strips itself from dependency crates and emits no trait impls, and once without. The dependency crate's rustc invocation was identical in both phases, so both compiles keyed the same and the normal build restored the stripped 264 KiB artifact instead of building the 620 KiB one. It surfaced as a missing trait impl at compile time; the same mechanism can just as easily produce a wrong binary that builds cleanly.

cache.key_env_vars declares the vars that steer expansion so the two modes get distinct entries:

[cache]
key_env_vars = ["BOLTFFI_*"]

Or via the environment (comma- or whitespace-separated; replaces the file list entirely):

export KACHE_KEY_ENV_VARS="BOLTFFI_BINDING_EXPANSION,BOLTFFI_SURFACE"

Semantics:

• Exact names, or a trailing * prefix glob. BOLTFFI_* selects every var starting with BOLTFFI_; APP_MODE selects only that name. Matching is ASCII case-insensitive, so a Windows environment behaves like a Unix one. A * anywhere but the end is a literal character — A*B matches a variable actually named A*B — and kache warns when it sees one, since that is almost never what someone meant.
• Turning it on re-keys the crate. The declared patterns are folded, not just the matched values — otherwise the build that leaves the vars unset would land back on the poisoned entry that made you reach for this setting. Expect one cold rebuild after adding or editing the list.
• Only vars actually set are folded, as NAME=VALUE pairs. Set-to-empty and unset are distinct, matching what std::env::var reports.
• Declaration spelling doesn't matter. The list is upper-cased, sorted and deduplicated before it is folded, so two teammates writing BOLTFFI_* and boltffi_* in either order still share a cache.
• Values are folded exactly, as their raw OS bytes. See the warning below.
• Off by default. An empty list has no effect; keys are byte-identical to not setting it.
• Union-only. A misdeclared pattern can cost a cache miss, never restore a wrong artifact.

Keep the list to vars that genuinely change what a macro emits. Naming something that varies per build — a timestamp, a job id, PWD — gives every compile its own key and disables caching for the whole workspace. "*" is a valid pattern and folds the entire environment, but for the same reason it is close to a cache-off switch, and it makes every credential in the process contribute to your cache keys.

Values are never written to logs or events — only variable names appear at KACHE_LOG=trace — but they do influence the resulting cache key, which is stored and (with a remote) transmitted. Treat a declared secret as hashed, not as hidden.

If you would rather not cache the affected crate at all, cache.exclude takes a source-path glob and bypasses kache entirely for those compiles.

Extra cc allowlist flags

kache caches a C/C++ compile only when it recognizes every flag on the command line. Its cc flag classifier is an allow-list: each flag is one kache has reasoned about and knows how to key. Anything unrecognized is refused and the compile passes through uncached — the safe default, since a flag kache doesn't model could change the object file without changing the key.

For setup and the current C/C++ support matrix, see C/C++ caching.

Supported compilers and dialects. kache wraps the GNU-dialect drivers (cc, c++, gcc, g++, clang, clang++; POSIX) and the MSVC-dialect clang-cl (Windows, or clang --driver-mode=cl). The two dialects have separate allow-lists, so each flag is classified in the spelling its compiler actually uses — e.g. -fno-rtti (GNU) vs -GR- (clang-cl), -std=c++20 vs -std:c++20. For clang-cl, debug info (/Z7 / -Z7 / -g) is cached (machine-local — clang-cl embeds CodeView paths in the .obj), while -bigobj and -showIncludes are still deliberately refused (passed through) for now; the common MSVC codegen set (-EH*, -GR/-GS, -guard:, -std:, -fms-compatibility-version=, /O*, -Gy/-Gw, -MD/-MT, …) is modeled. extra_allowlist_flags entries below are matched against command-line tokens verbatim, so list them in whichever dialect your compiler speaks (a /-spelled clang-cl flag included).

The cost is that a common-but-unlisted flag disables caching for that compile until kache ships a release adding it. cc.extra_allowlist_flags lets you opt such a flag in locally, ahead of official support:

[cc]
extra_allowlist_flags = ["-ffunction-sections", "-fdata-sections", "-fno-rtti"]

Or via the environment (whitespace-separated; overrides the file):

export KACHE_CC_EXTRA_ALLOWLIST_FLAGS="-ffunction-sections -fdata-sections"

Semantics:

• Exact match. An entry matches a command-line token character-for-character — no prefixes or wildcards. List each value you use (e.g. -march=armv8.2-a, not -march=).
• Hashed verbatim. A matched flag that's actually present is folded into the cache key as its literal string, so a different flag (or value) always produces a different key — it can never miscache by value.
• Add-only. This can only make kache stop refusing a flag. It cannot override structural refusals — link mode, coverage instrumentation, multi--arch, precompiled headers, modules, and the like still pass through.
• Off by default. An empty list has no effect; keys are byte-identical to not setting it.

To confirm it took effect, run with KACHE_LOG=kache=debug: the cc flag-classify summary gains a user-allowed count, and the flag no longer appears in any unsupported flag(s): … — passthrough line. At kache=trace each accepted flag logs as user-allowed (config) and each one folded into the key logs as cc_extra_flag=.

S3 credential resolution order

Remote S3 credentials are resolved in this order:

1. KACHE_S3_ACCESS_KEY + KACHE_S3_SECRET_KEY
2. Standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
3. Static credentials in the selected profile (KACHE_S3_PROFILE, cache.remote.profile, AWS_PROFILE, then default)
4. Legacy inline SSO, then credential_process for the selected profile
5. Environment-based web identity, ECS/task credentials, then EC2 instance credentials

For Ceph, MinIO, or R2, set cache.remote.endpoint or KACHE_S3_ENDPOINT.

[cache.remote]
type = "s3"
bucket = "build-cache"
endpoint = "https://s3.example.com"
profile = "ceph"

Composing with other compiler wrappers

kache works as a RUSTC_WRAPPER and composes with a second wrapper in either direction.

Behind another workspace wrapper (RUSTC_WORKSPACE_WRAPPER, e.g. clippy-driver): when cargo has both RUSTC_WRAPPER=kache and a RUSTC_WORKSPACE_WRAPPER set, it invokes kache <workspace-wrapper> <rustc> <args>. kache detects that the inner argument is itself a compiler, forwards the real rustc path as the workspace wrapper expects, and keys/caches around it. cargo clippy (which drives clippy-driver) is handled the same way — no extra configuration needed.

In front of another wrapper — when you want a second wrapper to cache the compiles kache declines: set KACHE_FALLBACK (or cache.fallback). kache then runs <fallback> <compiler> <args> for passed-through invocations, so e.g. sccache gets a chance at the compiles kache won't cache.

Restore verification

By default, a hit checks recorded metadata and blob size, then restores the blob. Set KACHE_VERIFY_RESTORES=sampled to content-hash roughly one in sixteen hits, or KACHE_VERIFY_RESTORES=always to hash every restored blob before serving it:

KACHE_VERIFY_RESTORES=sampled cargo build

sampled is useful as cheap background coverage for silent disk corruption. always is stricter but adds an extra full read of every restored blob.

Size values

Size fields (KACHE_MAX_SIZE, cache.local_max_size) accept human-friendly strings:

50GiB   10GB   512MiB   1024MB

Log levels

KACHE_LOG follows the tracing subscriber syntax:

KACHE_LOG=kache=debug   # verbose, useful when diagnosing cache misses
KACHE_LOG=kache=info    # operational detail
KACHE_LOG=kache=warn    # default — only surface real problems

The file log is written to ~/Library/Logs/kache/kache.log on macOS and ~/.cache/kache/kache.log elsewhere. It rotates automatically when it exceeds 5 MB.

Local store layout

<cache_dir>/               # Linux: ~/.cache/kache · macOS: ~/Library/Caches/kache · Windows: %LOCALAPPDATA%\kache
├── store/
│   ├── blobs/
│   │   └── ab/
│   │       └── abcdef...   # content-addressed blob (blake3), stored once
│   └── <cache_key>/
│       └── meta.json       # entry metadata; references its blobs by hash
├── index.db                # SQLite index (WAL mode) — sibling of store/, not inside it
├── events.jsonl            # build event log
├── transfers.jsonl         # transfer log
└── daemon.sock             # daemon IPC socket (a named pipe on Windows)

The whole cache directory is excluded from Time Machine and Spotlight on macOS automatically — on first start the daemon sets a tmutil exclusion and a .metadata_never_index sentinel.

Containers and cross-compilation

kache's index (index.db) is a SQLite database, and SQLite needs reliable file locking from the filesystem it lives on — plus shared memory, in WAL mode. A normal local cache directory provides both. A cache directory shared across machine or OS boundaries does not.

The usual way to hit this is bind-mounting your host cache directory into a build container — for example cross, Docker, or Podman:

• The directory is mounted from the host into the container, so index.db is opened from two different operating systems at once.
• A kache daemon on the host typically holds index.db open in WAL mode for the duration of the build, and that WAL state cannot be shared with the process inside the container.

When kache can't open the index it falls back to building uncached — your build still succeeds, just with no cache hits or stores — and prints a one-time warning:

[kache] the cache index could not be opened after retries (...).
[kache] Caching is disabled for this build — compilation still succeeds,
[kache] just without cache hits or stores (everything builds uncached).
[kache] ...
[kache] → set KACHE_CACHE_DIR to a fast, local, single-machine path

Give the container its own cache directory. Point KACHE_CACHE_DIR at a path the container alone uses — ideally a dedicated volume so the cache persists across runs:

# inside the container / cross build — a container-local volume, NOT the host's cache dir
export KACHE_CACHE_DIR=/kache-cache

Don't bind-mount the host's cache directory into the container. Sharing it gains little anyway: host and cross builds target different platforms and feature sets, so they produce different cache keys and would not reuse each other's entries.