Commands

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

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:

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:

[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.