Persistent Volumes & Caching

Standard Codex microVMs are ephemeral — everything is destroyed after the task completes. Persistent volumes break this model by providing storage that survives across tasks. A persistent volume is a block device that is attached to the microVM at boot and detached (but not destroyed) at shutdown. The next task can reattach the same volume and access its contents. This enables dependency caching (node_modules, pip cache, build artifacts), dataset persistence (large files that are expensive to re-download), and incremental build state.

Persistent volumes introduce complexity that ephemeral microVMs deliberately avoid. State that persists across tasks can become stale, corrupted, or inconsistent. A cached node_modules directory from last week may have different versions than today's lock file. A build cache from a different branch may produce incorrect incremental builds. The discipline is clear: use persistent volumes for caching layers that have built-in invalidation (package managers already handle this), not for application state that requires manual consistency management.

# Persistent volume configuration

volumes:
  deps-cache:
    size: 10 GB
    mount: /cache/deps
    scope: repository     # Shared across tasks for this repo
  build-cache:
    size: 5 GB
    mount: /cache/build
    scope: branch          # Per-branch build cache

# Usage in AGENTS.md
## Caching
- npm cache: /cache/deps/npm
- pip cache: /cache/deps/pip
- Build output: /cache/build/dist

# Invalidation strategy
- deps-cache: Invalidated when lockfile hash changes
- build-cache: Invalidated when branch changes
- Manual: Delete and recreate via cloud CLI

1. Identify cacheable layers List everything installed during task boot. Dependencies, build tools, and downloaded assets are candidates. Application state and git content are not.
2. Set invalidation triggers For each cached layer, define what triggers invalidation. Lockfile hash for dependencies, branch name for build cache, explicit TTL for downloaded assets.
3. Monitor cache hit rates Track how often tasks use cached vs fresh dependencies. A low hit rate means your invalidation is too aggressive or your dependencies change too frequently.