---
title: Daemon overview
description: What the background daemon owns and what still works without it
---
The daemon keeps network and maintenance work away from compiler processes. Local cache lookup and storage do not require it.
## Responsibilities
- Download an exact entry after a local miss.
- Store completed C/C++ compiles handed over by wrappers.
- Upload newly stored entries in the background.
- Replay durable upload intents after a restart.
- Prefetch likely entries at the start of a build session.
- Refresh the remote key index used by fallback planning.
- Run garbage collection at startup and every six hours, including `[cache.volumes]` shards. When the store is over its size limit, also sweep after an upload or when a wrapper reports it.
- Flush entries that were stored without an fsync, every two seconds.
- At the start of a build, copy large executables next to the paths their restore will write, so the restore only renames the copy into place.
- When the machine is quiet, heal the blob index and compact `index.db`.
- When the machine is quiet, at most once an hour, remove tracked target directories whose workspace was deleted, and build units no build has used for 30 days. See [Target directory cleanup](/docs/getting-started/configuration#target-directory-cleanup).
- While the machine is idle, replace target files that are full copies of stored blobs with clones of those blobs.
- Copy another checkout's registry and git dependency units into a new target directory before Cargo checks it. See [New checkouts](/docs/getting-started/configuration#new-checkouts).
- Fetch input-prediction rows from the remote, and publish them to a writable one.
- When a build session that used a writable remote has been idle for five minutes, publish its build manifest.
- Track running compiles for `kache monitor`.
- On macOS, exclude the cache directory from Spotlight and Time Machine.
- Exit when its config file changes, so the next start loads the new settings.
With `cache.daemon_publish` enabled (the default), a C/C++ wrapper can hand its private output snapshots to the daemon. The compiler still runs in the wrapper. If the daemon cannot accept the work within 25 ms, the wrapper keeps the local publication path. A compile whose store is a `[cache.volumes]` shard always stores from the wrapper.
Report JSON marks daemon publication attempts with `store_handed_off` and records their background time in `daemon_store_ms`. That time is separate from the wrapper's `store_ms`. A daemon crash can lose queued cache entries; the compiler outputs remain available to the build.
Set `cache.prefetch_enabled = false` or `KACHE_PREFETCH_ENABLED=0` to disable speculative prefetch while retaining exact remote checks and uploads.
The daemon lists the remote's keys only when `cache.remote_key_listing` is on. It is on by default for a filesystem remote and off for S3, GCS and OCI; on S3 it needs `s3:ListBucket`. Nothing is listed while `cache.prefetch_enabled` is off. The planner uses this key index for crates that no build manifest, shard or local history covers, and the daemon refreshes it every `cache.remote_key_cache_refresh_secs` (60 by default; `0` lists once). If S3 refuses the listing for lack of `s3:ListBucket`, the daemon stops listing and logs one warning.
## When it is required
Local-only caching works with no daemon. Compiler-driven remote reads, writes, and prefetch need the daemon. `kache sync` can transfer entries directly without it. If the daemon is unavailable, the wrapper continues with the local store and compiles an exact remote miss locally.
## Endpoint placement
The runtime directory defaults to the cache directory. On Unix the default socket is `<runtime_dir>/daemon.sock`; Windows derives a named-pipe name from that path. Move the runtime directory with `[cache] runtime_dir` or `KACHE_RUNTIME_DIR`, or only the endpoint with an absolute `KACHE_SOCKET_PATH`. `KACHE_SOCKET_PATH` has no config-file key, and a relative or unusable value is ignored with a warning.
The daemon also binds a lifecycle control endpoint next to the socket: the socket path with its extension replaced by `.ctl`. With the default `daemon.sock` it is one byte shorter than the socket. A custom `KACHE_SOCKET_PATH` without an extension gets a longer one.
Use a short, user-owned runtime directory. Unix socket paths are limited to 103 bytes on macOS and 107 on Linux. `kache daemon start` checks both endpoint paths against that limit and refuses to start a daemon when either is too long. Shared temporary directories also allow another local user to interfere with adjacent lock and state files.
Every client and daemon process must resolve the same runtime and socket settings. Installed services do not inherit later shell exports; put persistent values in the config or service definition.
## Basic commands
```bash
kache daemon start
kache daemon status
kache daemon log
kache daemon stop
```
Bare `kache daemon` is an alias for `kache daemon status`.
See [Lifecycle](/docs/daemon/lifecycle) for service installation and restart behavior.