Skip to main content
The Execution service schedules and executes actions on remote workers, enabling distributed builds.

​
Overview

The Execution service:
  • Accepts action execution requests
  • Schedules actions on available workers
  • Streams execution updates and results
  • Supports action cache integration
Key features:
  • Distributed action execution
  • Platform-based worker matching
  • Action cache lookup
  • Real-time execution monitoring

​
Configuration

​
instance_name
string
required
The instance name identifying this execution endpoint
​
scheduler
string
required
Reference to the scheduler configured in the schedulers section
​
cas_store
string
required
Reference to the CAS store for input/output data
{
  services: {
    execution: [
      {
        instance_name: "main",
        scheduler: "MAIN_SCHEDULER",
        cas_store: "MAIN_CAS_STORE"
      }
    ]
  }
}

​
gRPC Methods

​
Execute

Execute an action remotely. Request:
​
instance_name
string
required
The instance name
​
action_digest
Digest
required
Digest of the Action message to execute
​
skip_cache_lookup
boolean
default:false
Skip action cache lookup and force execution
​
execution_policy
ExecutionPolicy
Execution constraints (priority, timeout)
​
results_cache_policy
ResultsCachePolicy
How to cache the result
Response (stream): The Execute method returns a stream of Operation messages with status updates:
​
name
string
Unique operation identifier
​
done
boolean
True when execution is complete
​
metadata
ExecuteOperationMetadata
Execution status:
  • QUEUED: Waiting for worker
  • EXECUTING: Running on worker
  • COMPLETED: Finished
​
response
ExecuteResponse
Final result (when done=true):
  • result: ActionResult with outputs
  • status: gRPC status
  • cached_result: True if served from cache
  • message: Error message if failed
Example with grpcurl: 
grpcurl -plaintext \
  -d '{
    "instance_name": "main",
    "action_digest": {
      "hash": "abc123...",
      "size_bytes": 256
    },
    "skip_cache_lookup": false
  }' \
  localhost:50051 build.bazel.remote.execution.v2.Execution/Execute

​
WaitExecution

Attach to an ongoing execution operation. Request:
​
name
string
required
The operation name from Execute
Response (stream): Returns a stream of Operation messages (same format as Execute).

​
Execution Flow

1

Action cache lookup

If skip_cache_lookup is false, check the action cache first
2

Worker matching

Find workers matching the platform properties
3

Action queuing

Queue the action for an available worker
4

Input download

Worker downloads inputs from CAS
5

Execution

Worker executes the command
6

Output upload

Worker uploads outputs to CAS
7

Result caching

Store result in action cache if cacheable

​
Platform Properties

Actions specify required worker capabilities via platform properties: 
{
  "properties": [
    {"name": "OSFamily", "value": "Linux"},
    {"name": "cpu_count", "value": "4"},
    {"name": "memory_kb", "value": "8388608"}
  ]
}
Workers must match these properties to execute the action.

​
Timeout Configuration

Executions can timeout at multiple levels:
​
execution_policy.timeout
Duration
Maximum execution time (from client)
​
scheduler.max_job_retries
uint32
Retry failed actions up to N times
​
scheduler.worker_timeout_s
uint32
Worker heartbeat timeout

​
Error Codes

CodeDescription
NOT_FOUNDAction digest not in CAS
INVALID_ARGUMENTInvalid action or instance name
DEADLINE_EXCEEDEDExecution timeout
RESOURCE_EXHAUSTEDNo workers available
FAILED_PRECONDITIONMissing inputs
INTERNALWorker or storage error

​
Monitoring

The execution service emits metrics:
  • Queue depth per instance
  • Active executions
  • Cache hit rate
  • Execution duration
The Execution service follows the Remote Execution API v2 specification

Build docs developers (and LLMs) love

Get started for freeTalk to us