# Caching

Choose GitHub, Cloudflare, machine storage or no cache without changing your workflow.

## 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.

| Selection | Where archives live |
| --- | --- |
| GitHub hosted | GitHub's normal Actions cache service |
| Cloudflare hosted | Configured Cloudflare R2 storage |
| Machine hosted | Persistent storage on the paired machine, with configured R2 backing storage |
| None | Restores return misses; saves are skipped |

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

## 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.