---
title: Daemon lifecycle
description: Start, stop, install, update, and troubleshoot the daemon
---
## Commands
```bash
kache daemon # status
kache daemon start # background process; waits for readiness
kache daemon stop # graceful drain, bounded to 30 seconds
kache daemon restart # service-manager restart or manual replacement
kache daemon run # foreground process
kache daemon log # follow logs
```
Use `KACHE_LOG=kache=debug kache daemon run` for foreground debugging.
## Install a login service
```bash
kache daemon install
```
On macOS this installs `~/Library/LaunchAgents/ninja.kunobi.kache.plist`. On Linux it installs and enables the `kache.service` systemd user unit.
Remove either service with:
```bash
kache daemon uninstall
```
On current macOS releases, the first connection to a LAN cache endpoint may ask for Local Network permission. If an older service installation reports `No route to host`, reinstall it with the current Kache binary.
## Updates and config changes
The daemon records the running binary's build epoch. A newer client asks an older daemon to drain and exit. The service manager restarts installed services; otherwise later background work starts a fresh daemon.
The daemon also fingerprints the active config file and restarts after it changes. Environment is fixed at process start, so changing an export requires a daemon started from the new environment. An installed service uses its stored environment.
## Idle shutdown
The default idle timeout is disabled:
```toml
[cache]
daemon_idle_timeout_secs = 600
```
The equivalent environment variable is `KACHE_DAEMON_IDLE_TIMEOUT`. A later build can start the daemon again.
## Offline behavior
When the daemon cannot be reached:
- local hits and local stores continue
- exact remote checks and prefetch are skipped
- validated upload intents remain in `<cache_dir>/upload-queue`
- a later daemon replays queued uploads before retiring their files
The monitor falls back to direct store and event-log reads. Check `kache daemon log` when it remains offline.