---
title: Configuration
description: Config file, environment variables, and the TUI editor.
---
# 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:
```sh
kache config
```
The TUI editor shows all fields with their current values, marks which ones are coming from env vars, and lets you toggle or edit them interactively.
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`
A minimal config that enables a remote cache looks like this:
```toml title="~/.config/kache/config.toml"
[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
```
## All settings
| Environment variable | Config key | Default | Description |
|---|---|---|---|
| `KACHE_CACHE_DIR` | `cache.local_store` | `~/Library/Caches/kache` on macOS, `~/.cache/kache` on Linux | Local cache directory |
| `KACHE_MAX_SIZE` | `cache.local_max_size` | `50GiB` | Maximum local store size |
| `KACHE_CONFIG` | — | XDG config path | Explicit config file path |
| `KACHE_S3_BUCKET` | `cache.remote.bucket` | — | S3 bucket name |
| `KACHE_S3_ENDPOINT` | `cache.remote.endpoint` | — | S3 endpoint URL (required for Ceph, MinIO, R2) |
| `KACHE_S3_REGION` | `cache.remote.region` | `us-east-1` | AWS region |
| `KACHE_S3_PREFIX` | `cache.remote.prefix` | `artifacts` | Key prefix inside the bucket |
| `KACHE_S3_PROFILE` | `cache.remote.profile` | — | AWS credentials profile |
| `KACHE_S3_ACCESS_KEY` | — | — | Explicit S3 access key |
| `KACHE_S3_SECRET_KEY` | — | — | Explicit S3 secret key |
| `KACHE_CACHE_EXECUTABLES` | `cache.cache_executables` | `false` | Cache bin/dylib/cdylib/proc-macro outputs |
| `KACHE_CLEAN_INCREMENTAL` | `cache.clean_incremental` | `true` | Auto-clean tracked incremental dirs during GC; active builds also remove the current crate's incremental dir eagerly |
| — | `cache.exclude` | `[]` | Source-path glob patterns that bypass kache and compile normally without lookup, store, or upload |
| `KACHE_COMPRESSION_LEVEL` | `cache.compression_level` | `3` | Zstd compression level (1–22) |
| `KACHE_S3_CONCURRENCY` | `cache.s3_concurrency` | `16` | Max concurrent S3 operations |
| `KACHE_S3_POOL_IDLE_SECS` | `cache.s3_pool_idle_secs` | `300` | How long an idle S3 connection is kept in the HTTP pool. Higher values reuse warm TLS sessions across build phases; lower this if you sit behind a load balancer that drops idle connections aggressively |
| `KACHE_DAEMON_IDLE_TIMEOUT` | `cache.daemon_idle_timeout_secs` | `600` | Idle daemon shutdown timeout in seconds (`0` disables auto-shutdown) |
| `KACHE_KEY_SALT` | `cache.key_salt` | — | Opaque string folded into every cache key. Change it to force a cold cache on a toolchain change kache cannot otherwise see (see [Cache-key salt](#cache-key-salt)) |
| `KACHE_CC_EXTRA_ALLOWLIST_FLAGS` | `cc.extra_allowlist_flags` | `[]` | C/C++ flags to opt into caching that kache's built-in allow-list doesn't yet model (see [Extra cc allowlist flags](#extra-cc-allowlist-flags)). Env value is whitespace-separated |
| `KACHE_DISABLED` | — | `0` | Disable caching entirely (pass-through to rustc) |
| `KACHE_LOG` | — | `kache=warn` | Log level for stderr output |
| `KACHE_LOG_FILE` | — | `kache=info` | Log level for the file log |
| `KACHE_PROGRESS` | — | `auto` | CI progress lines: `always`, `never`, or `auto` |
`KACHE_PROGRESS=auto` (the default) prints per-crate progress lines to stderr when stderr is not a terminal. In CI this is usually the right behavior without any configuration.
## Excluding Sources
Use `cache.exclude` when a source file should compile normally but never use kache:
```toml title=".kache.toml"
[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.
## 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. That set is complete for divergences a tool reports in its version output. It is **not** complete for toolchain changes that alter compiled output while leaving every banner unchanged — most commonly a `glibc`, `mold`, or linker bump, 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:
```toml title=".kache.toml"
[cache]
key_salt = "nixpkgs-a1b2c3d-mold-2.40"
```
Or compute it from the toolchain itself:
```sh
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`:
```toml title="my-app/db/kache.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.
<Callout type="warn">
Keep patterns narrow. A glob that walks a huge tree (an absolute `/**`, or a
`**/*` that accidentally spans `target/`) re-keys on every change and re-walks
the tree on every compile — kache warns when a pattern matches the filesystem
root or an unusually large number of files.
</Callout>
<Callout type="info">
`kache.toml` (no leading dot) is **only** for `extra_inputs`. It is distinct
from the project config `.kache.toml`; any other key in it is a loud error.
</Callout>
## 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.
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:
```toml title=".kache.toml"
[cc]
extra_allowlist_flags = ["-ffunction-sections", "-fdata-sections", "-fno-rtti"]
```
Or via the environment (whitespace-separated; overrides the file):
```sh
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.
<Callout type="warn">
Avoid host-dependent flags like `-march=native`. The string is identical on every machine but compiles to different objects per CPU, so hashing it verbatim collides across hosts — a cache hit on one machine can restore an object built for another. List explicit architectures instead.
</Callout>
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=`.
## Credential resolution order
Remote S3 credentials are resolved in this order:
1. `KACHE_S3_ACCESS_KEY` + `KACHE_S3_SECRET_KEY`
2. AWS profile from `cache.remote.profile` or `KACHE_S3_PROFILE`
3. AWS default chain, such as `AWS_ACCESS_KEY_ID`, `~/.aws/credentials [default]`, or IAM roles
For Ceph, MinIO, or R2, set `cache.remote.endpoint` or `KACHE_S3_ENDPOINT`.
```toml title="Ceph example"
[cache.remote]
type = "s3"
bucket = "build-cache"
endpoint = "https://s3.example.com"
profile = "ceph"
```
## 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:
```sh
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/kache/ # Linux example
├── index.db # SQLite index (WAL mode)
├── events.jsonl # build event log
├── daemon.sock # daemon unix socket
└── store/ # content-addressed blobs
├── ab/
│ └── abcdef... # blake3 hash-named files
└── ...
```
The store directory is excluded from Time Machine and Spotlight on macOS automatically.