BuildFetch

Configure Sbt Remote Cache

Last updated: August 19, 2026

What is Sbt Remote Cache

sbt 2.0.0 introduced a hybrid local and remote caching system that can reuse cached task results and file outputs when a task's tracked inputs have not changed.

By default, cacheable tasks can reuse results through sbt local disk cache. Configuring Sbt Remote Cache allows to share the cache across machines.

Importantly: like Gradle and Bazel, Sbt also caches Test runs, this allows teams to save significant CI time and cost.

sbt 2.x comes with built-in Bazel-compatible gRPC REAPI Remote Cache implementation. Under the hood, sbt calls gRPC Remote Cache as per Bazel Remote Execution API spec:

  • Action Cache (AC) — stores cached task result metadata keyed by sbt's cached-task digest
  • Content-Addressable Storage (CAS) — stores output files and other content by digest
  • ByteStream — transfers larger CAS blobs over gRPC

BuildFetch Cache implements gRPC REAPI APIs natively, identifies sbt as a dedicated API client, and maintains a comprehensive end-to-end integration test suite to ensure full sbt Remote Cache compatibility across versions and workloads.

Schematic example: say a first run of Compile / compile misses both reusable local state and the shared Remote Cache, spends time compiling a module, then stores its cached task result and output blobs:

Diagram
Compile / compile

  Tracked task inputs
  +-----------------------------+
  | source / file hashes        |
  | dependent task values       |
  | relevant settings           |
  | compiler inputs             |
  | ...                         |
  +-------------+---------------+
                |
                v
  Compute cached-task digest
                |
                v
  +-----------------------------+
  | BuildFetch Remote Cache     |
  | task key: a3f9...c2         |
  | status: MISS                |
  +-------------+---------------+
                |
                v
  Run task locally
                |
                v
  Result + declared file outputs
                |
                v
  Store cache result + CAS blobs

Later builds with the same tracked inputs compute the same cached-task key and can restore the task result and file outputs from the shared cache instead of running the task again:

Diagram
Compile / compile  (same inputs)

  Tracked inputs unchanged
  sources · dependencies · settings · ...
                |
                v
  Same cached-task digest
                |
                v
  +-----------------------------+
  | BuildFetch Remote Cache     |
  | task key: a3f9...c2         |
  | status: HIT                 |
  +-------------+---------------+
                |
                v
  Restore cached task result
  + declared file outputs
                |
                v
  Skip local task execution
  Build graph continues sooner

BuildFetch Cache is specifically optimized to serve Action Cache metadata and CAS blobs quickly through its NVMe → SSD tiered storage system.

BuildFetch Cache correctly preserves AC → CAS references when entries are evicted via LRU GC, avoiding the failure mode where an Action Cache entry is still present but one or more referenced CAS blobs have already been removed.

When Sbt Remote Cache helps most

Sbt Remote Cache is especially valuable in ephemeral, autoscalable CI environments where build agents are frequently recreated without durable local disk state.

An actively developed repository can continuously warm the shared Remote Cache from CI as the codebase evolves. Engineer workstations, CI jobs, and AI agent environments then reuse compatible task results rather than spending time to execute tasks locally on every machine.

Configure Sbt Remote Cache

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

Official sbt 2.x Remote Cache documentation: https://www.scala-sbt.org/2.x/docs/en/reference/remote-cache-setup.html

The configuration on this page is specifically for sbt 2.x; sbt 1.x used a different Remote Cache mechanism.

Generate Tokens

We recommend starting with a cache:readwrite Token for CI and other trusted, reproducible environments that should populate the shared Sbt Remote Cache.

Generating cache:readwrite Tokens requires Project/Org Admin scope.

For Open Source Projects, we do not recommend storing Remote Cache Tokens as publicly accessible, doing so could result in unintended exhaustion of monthly Project limits.

Enable sbt Remote Cache

sbt 2.x requires its Remote Cache plugin to be enabled explicitly.

Add the following to project/plugins.sbt:

addRemoteCachePlugin

This enables the settings used by sbt's built-in gRPC Remote Cache client.

Configure BuildFetch Remote Cache

From the Project Cache Setup tab, take the HTTPS project cache host — for example cache.region.buildfetch.com — together with your Project ID and generated Token.

Set these environment variables in CI or another secret-managed environment:

export BUILDFETCH_SBT_REMOTE_CACHE_HOST="cache.region.buildfetch.com"
export BUILDFETCH_SBT_PROJECT_ID="project-id"
export BUILDFETCH_SBT_REMOTE_CACHE_TOKEN="..."

Then configure build.sbt:

val buildfetchCacheHost =
  sys.env("BUILDFETCH_SBT_REMOTE_CACHE_HOST")

val buildfetchProjectId =
  sys.env("BUILDFETCH_SBT_PROJECT_ID")

val buildfetchToken =
  sys.env("BUILDFETCH_SBT_REMOTE_CACHE_TOKEN")

ThisBuild / allowMachinePath := false

Global / remoteCache := Some(
  uri(s"grpcs://$buildfetchCacheHost/reapi/sbt/$buildfetchProjectId")
)

Global / remoteCacheHeaders +=
  s"authorization=Bearer $buildfetchToken"

The settings above configure:

  • BUILDFETCH_SBT_REMOTE_CACHE_HOST — the BuildFetch Cache hostname, without protocol prefix
  • BUILDFETCH_SBT_PROJECT_ID — namespace for Remote Cache isolation
  • BUILDFETCH_SBT_REMOTE_CACHE_TOKEN — Bearer token used as gRPC metadata
  • grpcs:// — TLS-enabled gRPC Remote Cache scheme
  • /reapi/sbt/<PROJECT_ID> — REAPI instance name for this sbt project
  • allowMachinePath := false — improves cache portability across machines

With the configuration loaded, use sbt normally:

sbt compile

or:

sbt test

Cacheable tasks participate in sbt's caching system automatically. No BuildFetch-specific logic is required.

See more