Caching

Choose a cache backend

In account settings, Caching sets the default for future Mirage jobs. Repository settings can override it or inherit the account default. Running jobs keep their original selection. Existing actions/cache restore/save steps and setup-action caches need no workflow changes.

Machine is the default. Cloudflare runners use configured R2 storage for Machine mode, because they have no persistent host disk. They continue uncached when storage is not configured. Managed selections require an updated host and runner image; Mirage shows an upgrade requirement on older machines. During the rollout, the selector shows when it is available.

The selection applies to Mirage-managed execution. Jobs routed to another provider follow that provider's caching behavior. Newly selected backends start cold; Mirage does not import archives from GitHub. Docker build-cache backends are separate from Actions caches.

Set up shared storage

Cloudflare cache storage is independent of Cloudflare execution. In account settings, choose Mirage managed storage or BYO account. BYO setup needs a Cloudflare account ID and an API token permitted to manage Workers, R2 buckets and Durable Objects. It creates a cache Worker, R2 bucket and quota controller. No Containers token is required. Mirage uses the provisioning token during setup and does not retain it.

Machine works locally without shared storage. With storage configured, it restores shared archives into the machine cache and mirrors completed saves to R2. A failed mirror warns and keeps the local archive. Each paired machine defaults to 10 GiB of persistent cache; its owner can adjust the limit in account settings. Zero uses only configured shared storage. The limit changes for future jobs. Proxmox caches live on the connector machine; if a guest cannot reach it, Mirage uses configured R2 storage or continues uncached.

Matching and access

Machine and Cloudflare share a namespace scoped to immutable account and repository identity, GitHub ref and cache version. Exact keys take priority over prefixes in the same ref, including when an exact entry is in R2 and a partial entry is local. Restore keys keep their workflow order. A run can also restore eligible base and default-branch caches; pull-request saves remain isolated to that pull request's merge ref. Existing keys are immutable and workflow cache-mode restrictions apply.

Cache outages warn and continue uncached. Mirage never switches to GitHub caching automatically. An explicit fail-on-cache-miss still fails when a restore misses. Logs, artifacts and other job results stay in GitHub.

Guests transfer archive bytes through a private authenticated endpoint; persistent host directories are not mounted into jobs. Cache access expires and is revoked when a job ends or is cancelled. Store secrets in GitHub Actions secrets, rather than in cache paths.