Build cache

The platform provides a remote build cache so builds reuse artifacts across machines and CI instead of rebuilding from scratch. It is configured for you by putnami cloud setup.

Setup writes .putnami/cache.json, which points at the cache and records a token source (never a raw bearer), so the file is safe to commit. Builds then read the shared cache automatically.

Only hosted Putnami CI writes to the shared cache. Your laptop, and any workspace machine token a member creates, read it and write nothing. The cache refuses their writes, even from a token created with cache.write, with a developer credential reads the shared cache; only CI writes to it.

An agent session or a CI job with no signed-in user reads the cache with a workspace machine token in PUTNAMI_CLOUD_TOKEN. See Agent and CI environments.

A pull request run stores each task's result and its files under 16 MiB. It leaves out a file of 16 MiB or more, such as a service executable. A run that needs one of those files rebuilds it. Runs on main store every file.

putnami cloud token --for cache mints a short-lived, workspace-scoped bearer with only cache.read. The CLI prints the bearer only; it does not persist the token in the cache configuration.

Manage it

Want to… Do this
Check the cache config, its identity, and how many tasks the last CI run took from the cache putnami cloud cache status
Disable the cache (keep the file) putnami cloud cache disable
Remove the cache config putnami cloud cache disable --remove
Re-provision during setup putnami cloud setup --cache
Skip provisioning during setup putnami cloud setup --no-cache
Mint a cache bearer for a script putnami cloud token --for cache
Read the cache where nobody signs in Set PUTNAMI_CLOUD_TOKEN; see Agent and CI environments

The cache negotiate mode (--cache-mode: minimal, toplevel, or full) is set at setup time.

Planned pages

Page Status
How the remote cache works Planned
Cache modes (minimal / toplevel / full) Planned
Using the cache in CI Planned
Disabling & troubleshooting Planned

Next