Skip to content

cache-storage.md

Latest commit

 

History

History
95 lines (75 loc) · 5.5 KB

cache-storage.md

File metadata and controls

95 lines (75 loc) · 5.5 KB
Raw

Set provider cache writes and storage

Last updated: 2026-10-24

Set a persistent write limit and optionally store encrypted inference caches on a separate disk. These commands affect cache payloads; use models location for downloaded weights.

Prerequisites

  • Use a storage device you own and trust. Darkbloom does not certify any disk model or vendor as free of malicious firmware. The storage trust model describes what the checks establish and the residual risks.
  • The selected disk must be mounted, local, writable APFS with ownership enabled. External volumes must use APFS (Encrypted). In Disk Utility, inspect the format; Apple documents supported formats. Back up existing data before changing a disk's format. Darkbloom does not format disks or change their encryption, permissions or mount settings.
  • Keep provider.toml (including any custom --config file) on trusted local storage, separate from the removable cache payloads.
  • Use an existing directory owned by your user without group/other write permission or write-granting ACL entries (including inherited grants). Read-only and deny ACL entries are allowed. On an external volume, ensure Ignore ownership on this volume is off in Finder's Get Info panel.

Steps

  1. Choose the daily write allowance in decimal GB. For example, 100 permits at most 100 GB of reserved cache-file writes in the rolling-day accounting window. 0 means unlimited. Failed writes consume their reservation; metadata writes and the drive's internal write amplification are additional. The accounting reference defines the window and disk-space safeguards.

    darkbloom cache set --daily-write-gb 100

  2. To select a separate disk, create a private directory on the mounted volume, then save it. You can combine both settings in one command:

    mkdir -m 700 "/Volumes/Cache SSD/provider-cache"
darkbloom cache set --daily-write-gb 100 --directory "/Volumes/Cache SSD/provider-cache"

    The CLI records the volume UUID. Cache files use its darkbloom/kv3 child (a dev build uses its own namespace instead of darkbloom); existing files are not copied or removed. A missing or different volume disables SSD caching while inference can continue without it. Normal expiration prevents reuse but cannot delete files on detached or previously selected disks. Cleanup needs the selected volume mounted and accessible; see the retention limits.

  3. Restart the provider to load the saved settings:

    darkbloom restart

    If you selected a custom --config file, pass that same file to all commands. A foreground/local provider needs to be stopped and started with its original serving command. The settings are read at process start.

Verify

darkbloom cache status
darkbloom cache status --json

Check the directory, saved daily allowance and storage result. Status is read-only and does not establish that an already-running provider reloaded its settings. If no allowance is saved, status reports it as unset: the running provider may have a startup environment different from the current shell. Set an explicit --daily-write-gb value when you want the same limit across launches. Use runtime cache observations to check caching activity. A valid disk does not imply every model supports caching.

Troubleshooting

Result Action
Missing directory / volume Mount and unlock the original volume, then restart the provider; recreate the private directory only on that volume
Volume UUID differs Reconnect the original disk. To deliberately select a replacement, run cache set --directory again
Ownership, ACL, filesystem or encryption check fails Inspect the volume and directory properties; active I/O also rechecks permissions and encryption. Do not disable macOS security controls to bypass the check
Return to the internal cache Run darkbloom cache set --reset-directory, then restart. This keeps the daily write choice and does not delete the external files
Daily cap exhausted Wait for old reservations to age out or explicitly change the allowance. Restarting or selecting another disk preserves the ledger on the Mac
status shows prefix_cache=FAILED (cache_init_failed: key_unavailable), or /metrics shows prefix_cache_status{…,detail="key_unavailable"} The provider could not load its persistent cache key and serves that model uncached: an ad hoc signed build has no keychain access group, and a Mac not unlocked since boot cannot use the key. Run a signed build, or log in once, then restart. A key sealed to a replaced Secure Enclave identity is replaced automatically. The logged cause is in runtime cache observations
status shows prefix_cache=FAILED (disk_unavailable: unsafe_path) The selected cache directory is missing, moved or unsafe. Follow the missing-volume or ownership rows above, then restart

Related