Cache Service
Client Configuration
Crab clients use the [cache] section in Crab config. Configure the service URL once, then provide secrets through user config or environment variables.
Minimal Configuration
[cache]
service_url = "https://crab-cache.example.com:8443"
service_mode = "cache+dedup"
service_auth = "psk"
push_warming = trueProvide the PSK separately:
export CRAB_CACHE_PSK="replace-with-shared-secret"Configuration Locations
Crab resolves cache settings from:
- User config:
~/.crab/config.toml - Repository config:
.crab/config.toml - Environment overrides for cache secrets
Use repository config for the cache URL when every checkout of a repository should use the same service. Use user config or environment variables for secrets.
Fields
| Field | Default | Description |
|---|---|---|
service_url | unset | Base URL of the cache service. When unset, the service is disabled. |
service_mode | cache+dedup | cache, dedup, or cache+dedup. |
service_auth | none | psk, bearer, or none. |
service_psk | unset | Shared secret for PSK auth. Prefer CRAB_CACHE_PSK for CI and user machines. |
service_token_path | unset | File containing a bearer token. |
service_ca_cert | system trust | PEM CA bundle for private TLS certificates. |
push_warming | true | Warm the cache after successful pushes. |
Modes
| Mode | Reads through cache | Dedup queries | Push warming |
|---|---|---|---|
cache | Yes | No | No |
dedup | No | Yes | No |
cache+dedup | Yes | Yes | Yes, when push_warming = true |
Use cache+dedup for normal team deployments.
Environment Overrides
| Variable | Effect |
|---|---|
CRAB_CACHE_PSK | Uses this value as the PSK secret. |
CRAB_CACHE_TOKEN | Uses this value as the bearer token. |
There is no environment override for service_url. Set the URL in TOML.
CI Example
- name: Configure Crab cache
run: |
mkdir -p ~/.crab
cat > ~/.crab/config.toml <<EOF
[cache]
service_url = "https://crab-cache-ci.example.com:8443"
service_mode = "cache+dedup"
service_auth = "psk"
push_warming = true
EOF
- name: Push
run: crab push origin HEAD:refs/heads/main
env:
CRAB_CACHE_PSK: ${{ secrets.CRAB_CACHE_PSK }}Set CRAB_CACHE_PSK on every CI step that runs crab.
Verification
Run a command with cache logging enabled:
RUST_LOG=info,crab::cache=debug crab fetchIf the cache service is healthy, the client enables remote cache behavior. If the service is unhealthy, Crab continues with local cache and origin access.