kache 0.6.0

Zero-copy, content-addressed Rust build cache. No copies, no wasted disk — just hardlinks locally and S3 for sharing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

---
title: kache
description: Zero-copy, content-addressed Rust build cache. No copies, no wasted disk — zero-copy restores (reflink where the filesystem supports it, else hardlink) locally and S3 for sharing.
---

# Introduction

**kache** is a drop-in `RUSTC_WRAPPER` that caches Rust compilation artifacts. Cache keys are blake3 hashes of normalized rustc invocations; cache hits restore zero-copy (reflink, with a hardlink/copy fallback on filesystems without CoW), and identical blobs are stored once and shared. Optional S3 sync (AWS, Ceph, MinIO, R2) shares the cache across machines. kache can also wrap C/C++ compiles (`CC="kache cc"`), though that coverage is narrower than rustc.

Local caching and direct S3 sync are stable today.

<Callout type="info">
**PREVIEW:** a remote planner that prefetches from workspace manifests, dependency history, and build intent — warming the right artifacts before rustc asks for them. The daemon already calls a planner when `KACHE_PLANNER_ENDPOINT` is set; the hosted service is still preview. See [Remote service](/docs/remote-service).
</Callout>

![kache: cold build populates the store, then `cargo clean && cargo build` restores every artifact zero-copy](https://raw.githubusercontent.com/kunobi-ninja/kache/main/assets/demo.gif)

> Cold compile populates kache's store, `cargo clean` wipes `target/`, and the second build pulls every artifact back zero-copy (reflink, falling back to hardlink/copy).

## Why local kache is fast

kache is useful even before remote cache is configured:

- **Zero-copy restores.** Local hits are restored without copying bytes — via reflink (copy-on-write) where the filesystem supports it (APFS, btrfs, XFS-with-reflink), and via hardlink on other filesystems.
- **Content-addressed storage.** The store is keyed by blake3 hash, so identical artifact blobs are stored once and linked many times.
- **Compile-then-record on misses.** Misses compile normally, then kache records the outputs for future builds.
- **Daemon-optional locally.** If the daemon is not running, local hits and misses still work; remote checks, uploads, and prefetching degrade gracefully.
- **Safer on macOS.** Incremental compilation is disabled on every platform while kache wraps rustc — artifact caching subsumes it. On macOS this also avoids APFS-related incremental-compilation corruption in git worktrees.

## Try it

```sh
# install
mise use -g github:kunobi-ninja/kache@latest

# interactive setup: cargo wrapper + login service + daemon start
kache init

# verify
kache doctor
```

`kache init` is idempotent — re-run it any time to repair configuration. Prefer to wire things by hand? Just export `RUSTC_WRAPPER=kache` or set `rustc-wrapper = "kache"` under `[build]` in `~/.cargo/config.toml`.

## Architecture in one screen

- **Wrapper** — `RUSTC_WRAPPER` intercepts rustc calls, computes blake3 cache keys, restores hits zero-copy (reflink, falling back to hardlink/copy).
- **Daemon** — background process handles async S3 uploads, remote checks, and prefetch. Auto-restarts on binary update.
- **Store** — SQLite index at `{cache_dir}/index.db`, plus content-addressed blobs under `{cache_dir}/store/blobs/`; hits restore those blobs into `target/` zero-copy (reflink, falling back to hardlink/copy).
- **Cache keys** — deterministic blake3 hash of rustc version, crate name, source, dependencies, and normalized flags — portable across machines.

<Cards>
  <Card title="Installation" href="/docs/getting-started/installation" description="mise, cargo-binstall, or build from source" />
  <Card title="Quick start" href="/docs/getting-started/quick-start" description="kache init, first build, verifying hits" />
  <Card title="How it works" href="/docs/how-it-works/architecture" description="Wrapper, store, daemon — the full picture" />
  <Card title="Cache key" href="/docs/how-it-works/cache-key" description="What's hashed and why keys are portable" />
  <Card title="Remote cache (S3)" href="/docs/remote-cache/s3-setup" description="AWS, R2, Ceph, MinIO — same config" />
  <Card title="CI setup" href="/docs/remote-cache/ci" description="GitHub Actions one-liner via kache-action" />
  <Card title="Monitor" href="/docs/monitor" description="Live TUI dashboard for builds, store, transfers" />
  <Card title="Commands" href="/docs/commands/reference" description="Every CLI subcommand with flags and examples" />
</Cards>