Manage the Cache and Clean Up
The resolved cache directory stores imported and prepared runtime artifacts. It comes from explicit x-slurm.cache_dir, then profile/default settings, then $HOME/.cache/hpc-compose. For real cluster runs, it must be visible from both the submission host and compute nodes; see Execution Model for why prepared artifacts must live on shared storage.
Choose A Cache Path
Use a project scratch, work, or shared filesystem path:
export CACHE_DIR=/cluster/shared/hpc-compose-cache
mkdir -p "$CACHE_DIR"
test -w "$CACHE_DIR"
You can record that path in project settings instead of every compose file:
hpc-compose setup --profile-name dev --cache-dir "$CACHE_DIR" --default-profile dev --non-interactive
Do not use /tmp, /var/tmp, /private/tmp, or /dev/shm. Validation may accept those strings, but preflight reports them as unsafe because compute nodes must reuse artifacts prepared before submission.
Inspect Cache State
hpc-compose cache list
hpc-compose cache inspect -f compose.yaml
hpc-compose cache inspect -f compose.yaml --service app
Use cache inspect to answer:
- which artifact is being reused
- whether a prepared image came from a cached manifest
- whether a service rebuilds on every prepare because prepare mounts are present
Staged-Input Cache (Datasets/Models)
Staged datasets and models live in a content-addressed store under the same shared cache root, at cache_dir/datasets/<key> and cache_dir/models/<key>. The key is derived from the input spec (its source URI and pinned revision), so identical staged inputs are materialized once and reused on every later run. Each staged directory carries a sidecar manifest (<key>.dataset.json or <key>.model.json) so cache list and cache prune cover staged inputs alongside image artifacts.
The store itself never fetches anything: it is a pure on-disk store, and the actual fetch and materialization (network) is approval-gated and introduced by the hf:// stage-in work, not run automatically by cache, plan, or prepare.
Prune Cache Entries
Prune old entries by age:
hpc-compose --profile dev cache prune --age 14 --yes
Prune artifacts not referenced by the current plan:
hpc-compose cache prune --all-unused -f compose.yaml --yes
Prune one cache directory directly:
hpc-compose cache prune --age 7 --cache-dir '<shared-cache-dir>' --yes
--age and --all-unused are mutually exclusive.
Rendezvous Records
Cross-job rendezvous records live under the same shared cache root and are pruned separately (rendezvous list, rendezvous prune). See Cross-Job Rendezvous for placement, TTL, and ownership rules.
Clean Up Old Tracked Runs
Tracked job metadata and logs accumulate in .hpc-compose/. Preview disk usage and cleanup before deleting:
hpc-compose jobs list --disk-usage
hpc-compose clean -f compose.yaml --age 7 --dry-run
hpc-compose clean -f compose.yaml --age 7
After Upgrading
Cache keys include the tool version, so upgrading hpc-compose invalidates existing cached artifacts. Expect a full rebuild on the next prepare or up, then optionally prune old entries:
hpc-compose cache prune --age 0 --yes