Scheduler Configuration

Schedulers manage task distribution to workers for remote execution.

Scheduler Definition

name

string

required

Unique identifier for the scheduler. Referenced in server execution services and worker configurations.

<type>

object

required

Scheduler type and configuration. Only one type can be specified.

Scheduler Types

Simple
GRPC
CacheLookup
PropertyModifier

Core scheduler for worker task distribution.

{
  name: "MAIN_SCHEDULER",
  simple: {
    supported_platform_properties: {
      cpu_count: "minimum",
      cpu_arch: "exact",
      OSFamily: "priority"
    },
    retain_completed_for_s: 60,
    worker_timeout_s: 5,
    max_job_retries: 3
  }
}

supported_platform_properties

object

Map of platform property names to match strategies. Keys must match worker-published capabilities.Property types:

"minimum" - Worker value must be >= task value (numeric)
"exact" - Worker value must exactly match task value (string)
"priority" - Informational, doesn’t restrict matching
"ignore" - Allows property in tasks without requiring worker support

supported_platform_properties: {
  cpu_count: "minimum",      // Worker needs >= cores
  memory_kb: "minimum",      // Worker needs >= memory
  cpu_arch: "exact",         // Must match exactly (e.g., "x86_64")
  gpu_model: "exact",        // Must match exactly
  OSFamily: "priority",      // Preference hint
  "container-image": "priority"
}

retain_completed_for_s

number

default:"60"

Seconds to keep completed action results in memory for WaitExecution calls.

client_action_timeout_s

number

default:"60"

Mark actions as failed if no client updates within this duration.

worker_timeout_s

number

default:"5"

Remove workers from pool after this many seconds without keepalive.

max_action_executing_timeout_s

number

default:"0"

Maximum time an action can execute without worker updates before timing out and re-queueing. Set to 0 to disable (rely only on worker_timeout_s).

max_job_retries

number

default:"3"

Maximum retries for jobs that fail with internal errors or timeouts.

allocation_strategy

enum

default:"least_recently_used"

Worker selection strategy when multiple workers can run a task.Options:

least_recently_used - Prefer idle workers
most_recently_used - Prefer active workers

worker_match_logging_interval_s

number

default:"10"

Log worker matching status every N seconds. Set to -1 to disable.

experimental_backend

object

Storage backend for scheduler state.

Show backend types

memory

object

In-memory backend (default, non-persistent).

experimental_backend: "memory"

redis

object

Redis-backed persistent scheduler.

experimental_backend: {
  redis: {
    redis_store: "REDIS_STORE_NAME"
  }
}

redis_store

string

required

Reference to a redis_store configuration.

Forwards scheduling requests to remote scheduler.

{
  name: "REMOTE_SCHEDULER",
  grpc: {
    endpoint: {
      address: "grpc://scheduler.example.com:50052"
    },
    connections_per_endpoint: 5,
    max_concurrent_requests: 100
  }
}

endpoint

object

required

Remote scheduler endpoint.

Show endpoint properties

address

string

required

GRPC endpoint URL (e.g., grpc://host:port or grpcs://host:port).

tls_config

object

TLS configuration for grpcs://.

Show tls properties

ca_file

string

Certificate authority file path.

cert_file

string

Client certificate file path.

key_file

string

Client private key file path.

concurrency_limit

number

Maximum concurrent requests to this endpoint.

connect_timeout_s

number

default:"30"

TCP connection timeout (seconds).

tcp_keepalive_s

number

default:"30"

TCP keepalive interval (seconds).

http2_keepalive_interval_s

number

default:"30"

HTTP/2 PING interval (seconds).

http2_keepalive_timeout_s

number

default:"20"

HTTP/2 PING timeout (seconds).

retry

object

Retry configuration for failed requests.

Show retry properties

max_retries

number

default:"0"

Maximum retries (0 = unlimited).

delay

number

default:"0"

Initial delay for exponential backoff (seconds).

jitter

number

default:"0"

Jitter factor (0-1) for randomized delays.

max_concurrent_requests

number

default:"0"

Global concurrent request limit (0 = unlimited). Requests queue when limit is reached.

connections_per_endpoint

number

default:"1"

Number of TCP connections per endpoint for load balancing.

Checks Action Cache before delegating to nested scheduler.

{
  name: "CACHED_SCHEDULER",
  cache_lookup: {
    ac_store: "AC_STORE",
    scheduler: {
      simple: { /* ... */ }
    }
  }
}

ac_store

string

required

Reference to Action Cache store. Should be a completeness_checking store to verify result validity.

scheduler

object

required

Nested scheduler to use on cache miss.

Modifies action platform properties before scheduling.

{
  name: "MODIFIED_SCHEDULER",
  property_modifier: {
    modifications: [
      { add: { name: "pool", value: "default" } },
      { remove: "deprecated_property" },
      { 
        replace: {
          name: "os",
          value: "linux",
          new_name: "OSFamily",
          new_value: "Linux"
        }
      }
    ],
    scheduler: { simple: { /* ... */ } }
  }
}

modifications

array

required

Ordered list of property modifications applied to each action.

Show modification types

add

object

Add a property.

{ add: { name: "pool", value: "gpu" } }

name

string

required

Property name.

value

string

required

Property value.

remove

string

Remove a property by name.

{ remove: "unwanted_property" }

replace

object

Replace matching property.

{
  replace: {
    name: "cpu_arch",
    value: "amd64",
    new_name: "cpu_arch",
    new_value: "x86_64"
  }
}

name

string

required

Property name to match.

value

string

Value to match (omit to match any).

new_name

string

required

New property name.

new_value

string

New value (omit to keep original).

scheduler

object

required

Nested scheduler that receives modified actions.

Platform Properties

Platform properties match tasks to workers. Workers advertise capabilities, and the scheduler filters based on property type:

Property Type	Behavior	Example Use Case
`minimum`	Worker value >= task value	CPU cores, memory, disk
`exact`	String exact match	Architecture, OS, GPU model
`priority`	Soft preference	Container images
`ignore`	Accept task property without worker requirement	Optional labels

Example Configuration

{
  name: "PRODUCTION_SCHEDULER",
  simple: {
    supported_platform_properties: {
      // Resource minimums
      cpu_count: "minimum",
      memory_kb: "minimum",
      disk_read_iops: "minimum",
      
      // Exact matches
      cpu_arch: "exact",        // "x86_64", "aarch64"
      cpu_vendor: "exact",      // "intel", "amd"
      OSFamily: "exact",        // "Linux", "Windows"
      
      // Preferences
      "container-image": "priority",
      
      // Optional
      "build-id": "ignore"
    },
    allocation_strategy: "least_recently_used",
    worker_timeout_s: 10,
    max_job_retries: 5
  }
}

Configuration Reference

Examples

Scheduler Configuration

Scheduler Definition

Scheduler Types

Platform Properties

Example Configuration

Build docs developers (and LLMs) love

Configuration Reference

Examples

​Scheduler Definition

​Scheduler Types

​Platform Properties

​Example Configuration

Build docs developers (and LLMs) love

Scheduler Definition

Scheduler Types

Platform Properties

Example Configuration