crab cache
Manage the local chunk cache.
Synopsis
crab cache stats
crab cache verify
crab cache cleanDescription
crab cache manages the local chunk cache that stores previously downloaded
xorb data. The cache speeds up repeated hydrations by avoiding redundant
downloads from cloud storage.
For conceptual background, see Local Cache.
Subcommands
stats
Show the configured size limit, resident bytes, and entry count for the xet range cache, plus a size and object-count breakdown for Crab's local object cache. Range-cache entries are streamed on a blocking worker, so a large cache does not retain its complete file inventory or block the async runtime.
crab cache statsclean
Remove cached data to free disk space.
crab cache cleanThe current cache subcommands do not add command-specific selection flags;
use crab cache <command> --help for global logging options.
verify
Validate content-addressed chunks, shards, and xorbs plus xet range filenames,
lengths, offset headers, and CRCs, then evict corrupt entries. Range entries are
verified as they are scanned. I/O failures fail the command. For a non-mutating
cleanup preview, use crab optimize cache clean --dry-run.
Remote Cache Service
The crab cache command manages your local disk cache — a per-machine store of previously downloaded chunks. For teams, Crab also supports an optional remote cache service (crab-cache-server) that shares cached objects across all developers and CI runners.
How They Relate
| Local Cache | Remote Cache Service | |
|---|---|---|
| Scope | Single machine | Entire team / org |
| Storage | Your local disk (~/.cache/crab/) | Dedicated server with NVMe |
| Population | Filled on fetch/hydrate | Filled on fetch + push warming |
| Eviction | LRU when over max_size | Background evictor with high/low watermarks |
| Setup | Zero config (automatic) | Requires server deployment |
When both are configured, Crab checks the local cache first. On a local miss, it queries the remote cache service before falling back to cloud storage. This means the first developer to fetch a file warms the remote cache, and every subsequent fetch across the team is served at network-local speed.
Enabling the Remote Cache
Add the cache service URL to your Crab config:
[cache]
service_url = "https://crab-cache.internal:8443"
service_auth = "psk"
service_psk = "my-secret-key"
push_warming = trueWith push_warming = true, newly pushed xorbs are sent to the remote cache immediately — teammates can hydrate without waiting for a cold-start download from S3.
For full deployment instructions, server configuration, and authentication setup, see the Cache Service guide.
Related Commands
crab hydrate— uses the cache during reconstruction.crab fetch— pre-fetch remote objects into the cache.crab du— includes cache in disk usage report.