BuildFetch

Configure Moon Remote Cache

Last updated: September 23, 2026

What is Moon Remote Cache

Moon by moonrepo can share cached task results across CI and developer machines for builds, tests, linting, typechecking, packaging, and other cache-enabled tasks. Task outputs are restored automatically on cache hits allowing CI, AI agents and developer machines to reuse work instead of rebuilding it locally.

Moon supports Remote Cache through the Bazel Remote Execution gRPC API (REAPI). BuildFetch Cache natively implements the required Action Cache, CAS, and ByteStream APIs for Moon and has dedicated client recognition and metrics.

Configure Moon Remote Cache

Before setting up Remote Cache, ensure you have created a BuildFetch Project and Token(s).

Cache Access

Use a cache:readonly Token on developer and AI agent machines. Trusted environments such as CI should use a cache:readwrite Token so they can populate the shared cache.

For Token management and rotation, see Set up BuildFetch Cache Project.

Configure Moon to use Remote Cache

Take the cache host, Project ID, and generated Token from the BuildFetch Project Cache Setup tab.

Configure .moon/workspace.yml:

remote:
  api: 'grpc'
  host: 'grpcs://cache.region.buildfetch.com'
  auth:
    token: 'BUILDFETCH_MOON_REMOTE_CACHE_TOKEN'
  cache:
    localReadOnly: true
    instanceName: 'reapi/moon/<PROJECT_ID>'

auth.token is the name of the environment variable, not the Token itself. Moon reads BUILDFETCH_MOON_REMOTE_CACHE_TOKEN at runtime and sends its value as Bearer authentication.

Keep the Token value outside source control:

export BUILDFETCH_MOON_REMOTE_CACHE_TOKEN="..."

The important settings are:

  • instanceName = reapi/moon/<PROJECT_ID> — identifies and isolates the BuildFetch Cache Project used by Moon.
  • localReadOnly: true — keeps local development read-only while Moon still uploads cache entries in CI environments.

Run Moon normally:

moon run app:build

Cacheable tasks automatically participate in Moon's local and Remote Cache. No BuildFetch-specific plugin or wrapper is required.

See Also