Problem
Today, bbox uses an implicit if-not-present pull policy via the ref index fast path in go-microvm. If the ref index has a hit (refs/ maps the image reference to a cached digest), no registry contact happens at all. This is great for performance but means:
- After pushing new images, you have to either
rm -rf the cache or use --no-image-cache (which also loses all caching benefits for the run)
- There's no way to say "use exactly what's cached, fail if missing" (useful for airgapped/offline environments)
Proposal
Add a --pull flag with three modes:
bbox claude-code --pull always # Always check registry for new digest
bbox claude-code --pull if-not-present # Use cache if available (default, current behavior)
bbox claude-code --pull never # Fail if image not in cache
always
Skip the ref index fast path. Still use the digest-based cache — if the registry returns the same digest, reuse the cached extraction. This means "check for updates" not "re-extract from scratch."
Implementation: pass a flag through to image.PullWithFetcher that skips the cache.LookupRef() call but still uses cache.Get(digest) after computing the digest from the fetched image.
if-not-present
Current behavior. No change needed.
never
Use cache.LookupRef() only. If it misses, return an error instead of fetching. Useful for:
- Offline/airgapped environments
- CI where images should be pre-warmed
- Testing that the cache is populated correctly
Config file support
# ~/.config/broodbox/config.yaml
image:
pull: always
CLI flag overrides config.
Notes
- This is a small change in go-microvm (
PullWithFetcher needs a pull policy parameter or option) plus CLI wiring in brood-box
--no-image-cache remains orthogonal — it disables caching entirely (no read or write), while --pull always still reads/writes the cache- The
--pull always + cache GC combination directly addresses the "I just rebuilt images" workflow: force a fresh registry check, and stale entries become unreachable for GC
Problem
Today, bbox uses an implicit
if-not-presentpull policy via the ref index fast path in go-microvm. If the ref index has a hit (refs/maps the image reference to a cached digest), no registry contact happens at all. This is great for performance but means:rm -rfthe cache or use--no-image-cache(which also loses all caching benefits for the run)Proposal
Add a
--pullflag with three modes:alwaysSkip the ref index fast path. Still use the digest-based cache — if the registry returns the same digest, reuse the cached extraction. This means "check for updates" not "re-extract from scratch."
Implementation: pass a flag through to
image.PullWithFetcherthat skips thecache.LookupRef()call but still usescache.Get(digest)after computing the digest from the fetched image.if-not-presentCurrent behavior. No change needed.
neverUse
cache.LookupRef()only. If it misses, return an error instead of fetching. Useful for:Config file support
CLI flag overrides config.
Notes
PullWithFetcherneeds a pull policy parameter or option) plus CLI wiring in brood-box--no-image-cacheremains orthogonal — it disables caching entirely (no read or write), while--pull alwaysstill reads/writes the cache--pull always+ cache GC combination directly addresses the "I just rebuilt images" workflow: force a fresh registry check, and stale entries become unreachable for GC