A filesystem remote uses the same logical objects as S3 but stores them below a shared directory.

[cache.remote]
type = "filesystem"
path = "/mnt/shared-kache"
prefix = "artifacts"

Use an absolute path mounted consistently on every machine. Keep cache.local_store on local storage; the local SQLite store is not designed for cross-machine sharing.

Trust and permissions

Every writer to the mount is trusted. A filesystem remote is not an isolation boundary. Use directory permissions or choose S3 with access policy when clients are not mutually trusted.

Kache validates paths and writes only below the configured root, but this is defense in depth rather than a substitute for mount security.

Atomic writes

Writes stage under <path>/.kache-tmp and then rename into place. Override the directory only when necessary:

[cache.remote]
type = "filesystem"
path = "/mnt/shared-kache"
atomic_write_dir = "/mnt/shared-kache/.staging"

The staging directory must:

• be on the same filesystem as path
• sit outside the object subtree <prefix>/v3/

Kache rejects a configuration that cannot provide atomic final renames.

Layout

/mnt/shared-kache/
├── .kache-tmp/
└── artifacts/
    ├── v3/manifests/{crate}/{key}.json
    ├── v3/packs/{crate}/{key}.tar.zst
    └── _manifests/

Filesystem prefixes cannot contain :.

Reclaim remote space

Local kache gc never deletes remote objects. Remote deletion is manual because no protocol coordinates deletion with in-flight readers and writers.

Use one designated deletion job and pause writers when pruning. Delete each manifest and pack pair together. For a small cache, removing the complete artifacts/ subtree and allowing it to repopulate is safer than an inconsistent partial prune.