6.1.3 Choosing Remote Cache or Execution

Remote caching and remote execution solve different problems. A cache lets one invocation reuse a result produced earlier; remote execution moves work to a shared worker fleet. The right choice can therefore be cache, execution, both, or neither—and the answer comes from measured workload costs, not from treating “remote” as automatically faster.

Start with the matched cohorts from 6.1.2 Measuring Builds Fairly. They keep journey, revision, requested scope, configuration, platform, cache temperature, action mix, and versions comparable. If the evidence instead points to loading, analysis, a needlessly broad target set, or an incorrect action, return to the profiling and observability workflow in 5.4 Performance and 5.5 Observability. Moving execution or results across a network does not repair those causes.

Use 6.1.4 Action and Result Lifecycle to distinguish lookup, queueing, execution, transfer, materialization, and reporting costs before comparing interventions.

Compare the Work That Disappears With the Work You Add

For one action class, describe each candidate as a change to the action's path:

• Local only: execute locally and materialize outputs locally.
• Remote cache: look up a prior result; on a usable hit, transfer the required outputs instead of executing. A miss still needs execution and may also upload the result.
• Remote execution: make inputs available to the service, wait for admission and scheduling, execute on a compatible worker, publish the result, and make required outputs available to the client.
• Both: reuse prior results when possible and send remaining eligible work to the worker fleet.

REAPI makes action caching, content-addressed storage, execution, capabilities, digests, and result messages distinct portable contracts; it does not prescribe one scheduler, storage layout, or production topology.¹ Cache and execution must be evaluated as separate interventions even when one backend supplies both.

Measure these factors by journey and action class. Production-representative evaluation must include both performance and total ownership cost rather than extrapolating from a curated sample alone.²

Factor	Question that changes the decision
Reuse	How often can another comparable invocation consume a usable prior result?
Granularity	Is the workload split into independently reusable and schedulable actions, or concentrated in a few coarse steps?
Duration	How much local execution does a hit avoid, and how long does a remotely executed miss take?
Transfer and materialization	How much input and output data crosses the boundary, and what must become available locally?
Local capacity	Is useful work delayed by constrained developer or CI CPU, memory, or concurrency?
Queueing	Does shared scheduling add delay, and is compatible capacity available for this action class?
Reliability	What happens to trustworthy results and the protected journey when the service is slow or unavailable?
Ownership cost	Who operates storage, scheduling, workers, monitoring, upgrades, security, and recovery, and what ongoing resources do they consume?

Do not turn any row into a universal threshold. Large outputs can make a cache hit expensive to consume; short actions can cost more to transfer and schedule than to run locally; long actions may still be poor remote candidates if they depend on undeclared host state. Conversely, a constrained local machine does not prove that a remote fleet helps if the relevant work is sequential or waits in an incompatible queue. Keep cache, queueing, parallelism, critical-path, and local-action symptoms as separate diagnoses for the same reason.

Choose Among Four Interventions

Choose remote cache

Prefer cache-only when comparable builds repeat enough action results that avoided recomputation outweighs lookup, transfer, upload, and materialization, while local machines still have adequate capacity for misses. This choice buys reuse without taking responsibility for scheduling and executing every miss on a worker fleet.

The decision is strongest when the measured improvement appears in the protected journey, not merely in hit rate. Detailed setup and cross-client proof are shown in 6.2.2 Setting Up a Shared Remote Cache; deciding whether transfer makes a hit worthwhile is developed in 6.2.5 When a Cache Hit Is Slower.

Choose remote execution

Prefer execution when misses contain eligible work whose local resource demand or concurrency is the constraint, and the measured remote path—including input availability, queueing, execution, result publication, and output access—beats or usefully relieves the local path. Low reuse can make cache-only ineffective while shared execution capacity still improves throughput.

This decision does not prove that actions are remote-ready or that a fleet is properly sized. Those are the next engineering questions in 6.3.1 Making Actions Work Remotely and 6.3.12 Remote Execution Capacity.

Choose both

Choose both when two independently supported claims hold: useful hits avoid enough recomputation, and the remaining eligible misses benefit from shared execution capacity after queue, transfer, and output costs. The cache reduces work offered to the fleet; the fleet handles worthwhile misses. NativeLink's separate CAS, scheduler, executor, metrics, and cache/execution integration-test surfaces make these independent responsibilities visible.³

Do not infer the combined choice from one successful remote build. Require evidence for the cache path and the execution path separately, plus the end-to-end journey result when they operate together.

Choose neither

Choose neither when reuse is too low, actions are too short or coarse, transfer and materialization dominate, local capacity is sufficient, remote queues erase the expected gain, reliability would worsen the protected journey, or the ownership cost is not justified by the measured outcome. “Neither” is a valid infrastructure decision, not a failure to modernize.

It can also be the correct answer for now: improve action structure, target selection, correctness, or local execution first, then repeat the same matched comparison. Do not hide a diagnosis by purchasing a service.

Repository size can change which constraint deserves measurement without choosing the intervention for you. H.10.3 Service Capacity supplies those monorepo-scale signals; return here with a matched workload before concluding that scale alone requires cache or remote execution.

Record a Decision That Can Be Reversed

Write one short decision memo for the selected journey and action classes:

1. Workload evidence: link the fair cohorts and record reuse, granularity, duration, transfer/materialization, local capacity, queueing, reliability, and ownership observations, including missing evidence.
2. Choice: name cache, execution, both, or neither and the mechanism expected to improve the journey.
3. Rejected alternatives: state which measured factor falsified each other option. Do not reject an option with “industry best practice.”
4. Risks and ownership: name the service responsibilities introduced by the choice. Runnable Buildbarn deployments show why frontend, storage, scheduler, runner, worker, configuration, and monitoring can be separate operational boundaries rather than one anonymous endpoint.⁴
5. Success and exit conditions: define correctness and completeness gates, the journey outcome expected to move, a stop signal, fallback, and the observation that would justify removing or revisiting the intervention.

The memo is not a deployment plan. It is the evidence-backed bridge from diagnosis to one infrastructure intervention. Cache configuration begins with 6.2.2 Setting Up a Shared Remote Cache; remote-execution repair and production proof continue through 6.3.1 Making Actions Work Remotely and 6.3.18 Remote Execution Production Readiness. Apply the compatibility-aware rollout in 6.1.5 Safe Infrastructure Rollouts, and design shared-service recovery with 6.6.6 Build-Service Incident Recovery only after the choice survives review.