BuildFetch

Configure Buck2 Remote Cache

Last updated: September 21, 2026

What is Buck2 Remote Cache

Buck2 can store and reuse metadata and output files from a shared Remote Cache for significantly faster builds using the Bazel Remote Execution gRPC API (REAPI). BuildFetch Cache acts as a fully compatible Remote Cache REAPI server for Buck2.

Remote Cache is especially useful for ephemeral CI workers, large monorepos, and teams that frequently switch branches or work across several machines.

Each CI build populates the shared cache, follow-up Buck2 builds then reuse the caches instead of spending minutes on executing the build graph.

Configure Buck2 Remote Cache

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

Cache Access

Use a cache:readonly Token by default on developer and AI agent machines. Trusted environments like CI should use a cache:readwrite Token and explicitly enable uploads.

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

Read-only

The execution platform defaults allow_cache_uploads to false, so normal Buck2 builds only consume remote cache entries:

buck2 build //...

Read-write

Enable uploads:

buck2 --config buildfetch.allow_cache_uploads=true build //...

Configure Buck2 to use Remote Cache

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

Add or merge these sections into .buckconfig:

[buck2]
digest_algorithms = SHA256

[buck2_re_client]
action_cache_address = grpcs://cache.region.buildfetch.com
engine_address = grpcs://cache.region.buildfetch.com
cas_address = grpcs://cache.region.buildfetch.com
tls = true
instance_name = reapi/buck2/<PROJECT_ID>
http_headers = Authorization:Bearer $BUILDFETCH_BUCK2_REMOTE_CACHE_TOKEN

[build]
execution_platforms = root//platforms:platforms

Keep the Token outside source control:

export BUILDFETCH_BUCK2_REMOTE_CACHE_TOKEN="..."

Buck2 controls cache participation through the execution platform. The following configuration keeps execution local while allowing BuildFetch Cache to serve and populate the remote cache:

# platforms/defs.bzl
def _platforms(ctx):
    configuration = ConfigurationInfo(
        constraints = {},
        values = {},
    )

    platform = ExecutionPlatformInfo(
        label = ctx.label.raw_target(),
        configuration = configuration,
        executor_config = CommandExecutorConfig(
            local_enabled = True,
            remote_enabled = False,
            remote_cache_enabled = True,
            allow_cache_uploads = read_config("buildfetch", "allow_cache_uploads", "false") == "true",
        ),
    )

    return [DefaultInfo(), ExecutionPlatformRegistrationInfo(platforms = [platform])]

platforms = rule(attrs = {}, impl = _platforms)

Register it from platforms/BUCK:

load(":defs.bzl", "platforms")

platforms(name = "platforms")

The important settings are:

  • remote_cache_enabled = True — Buck2 queries the remote Action Cache and CAS.
  • allow_cache_uploads — defaults to false through read_config, so local builds only consume remote cache entries.
  • remote_enabled = False — BuildFetch is not used as a remote executor.
  • instance_name = reapi/buck2/<PROJECT_ID> — identifies and isolates the BuildFetch Buck2 Project in BuildFetch Cache in conjunction with token.
  • digest_algorithms = SHA256 — matches the digest algorithm supported by the BuildFetch REAPI implementation.

See Also