Worker Configuration

Workers execute tasks scheduled by the scheduler. Only the local worker type is currently supported.

Worker Definition

local

object

required

Local worker configuration.

Local Worker

Executes tasks locally on the machine running NativeLink.

{
  workers: [
    {
      local: {
        name: "worker-1",
        worker_api_endpoint: {
          uri: "grpc://127.0.0.1:50061"
        },
        cas_fast_slow_store: "WORKER_STORE",
        work_directory: "/tmp/nativelink/work",
        platform_properties: {
          cpu_count: { values: ["16"] },
          cpu_arch: { values: ["x86_64"] },
          memory_kb: { values: ["32000000"] }
        }
      }
    }
  ]
}

Core Configuration

name

string

Worker identifier for logging and metrics. Defaults to array index. Used as prefix for worker ID ({name}-{uuid}).

worker_api_endpoint

object

required

Scheduler WorkerAPI endpoint.

Show endpoint properties

uri

string

required

Scheduler WorkerAPI URI (e.g., grpc://127.0.0.1:50061).

timeout

number

default:"5"

Request timeout (seconds).

tls_config

object

TLS configuration for grpcs://.

Show tls properties

ca_file

string

Certificate authority file.

cert_file

string

Client certificate file.

key_file

string

Client private key file.

cas_fast_slow_store

string

required

Reference to a fast_slow store. The fast store must be a filesystem store for hardlinking. The slow store must resolve to the same CAS the scheduler uses.

stores: [
  {
    name: "WORKER_STORE",
    fast_slow: {
      fast: {
        filesystem: {
          content_path: "/var/cache/nativelink/cas",
          temp_path: "/var/cache/nativelink/tmp",
          eviction_policy: { max_bytes: "50gb" }
        }
      },
      slow: {
        grpc: {
          endpoints: [{ address: "grpc://scheduler:50051" }],
          store_type: "cas"
        }
      }
    }
  }
]

work_directory

string

required

Directory for task execution. Must be on same filesystem as the fast store’s content_path for hardlinking. Purged on startup.

Platform Properties

platform_properties

object

required

Worker capabilities advertised to scheduler. Keys must match scheduler’s supported_platform_properties.Each property can be:

values - Static list of values
query_cmd - Command to execute for dynamic values (output split by newlines)

platform_properties: {
  cpu_count: { values: ["16"] },
  cpu_arch: { values: ["x86_64"] },
  memory_kb: { values: ["32000000"] },
  gpu_count: { values: ["2"] },
  gpu_model: { values: ["nvidia-t4"] },
  OSFamily: { values: ["Linux"] },
  "container-image": { values: [""] },
  
  // Dynamic property from command
  kernel_version: {
    query_cmd: "uname -r"
  }
}

Execution Settings

max_action_timeout

number

default:"1200"

Maximum action execution time (seconds). Tasks requesting longer timeouts are rejected. Default: 20 minutes.

max_upload_timeout

number

default:"600"

Maximum time for uploading results to CAS (seconds). Actions exceeding this fail with DeadlineExceeded. Default: 10 minutes.

max_inflight_tasks

number

default:"0"

Maximum concurrent tasks (0 = unlimited).

timeout_handled_externally

boolean

default:"false"

Disable NativeLink timeout enforcement. Set to true if entrypoint handles timeouts (e.g., docker containers with download time).When true:

Worker uses max_action_timeout for all actions
Actual timeout must be enforced via additional_environment with timeout_millis and side_channel_file

entrypoint

string

Command prefix for all actions. Parsed as command + args, not shell.Example: "entrypoint": "run.sh" with action command "sleep 5" executes as run.sh sleep 5.

entrypoint: "/usr/local/bin/wrapper.sh"

experimental_precondition_script

string

Script to run before each action. Worker pauses if script exits non-zero. Useful for resource checks.

experimental_precondition_script: "/usr/local/bin/check-resources.sh"

Result Upload

upload_action_result

object

Controls how action results are uploaded.

Show upload properties

ac_store

string

Action Cache store for results. If unset, results are not cached.

upload_ac_results_strategy

enum

default:"success_only"

When to upload to Action Cache.Options:

success_only - Only exit code 0
failures_only - Only non-zero exit codes
everything - All completed actions
never - Never upload

historical_results_store

string

CAS store for historical results (typically failures). Defaults to parent CAS store.

upload_historical_results_strategy

enum

default:"failures_only"

When to upload historical results.

success_message_template

string

Template for ExecuteResponse.message on success. Supports variables:

{digest_function} - Hash function
{action_digest_hash} - Action digest hash
{action_digest_size} - Action digest size
{historical_results_hash} - Historical result hash
{historical_results_size} - Historical result size

success_message_template: "https://ui.example.com/{digest_function}/action/{action_digest_hash}-{action_digest_size}/"

failure_message_template

string

Template for failure messages. Uses same variables as success_message_template.

failure_message_template: "https://ui.example.com/{digest_function}/historical/{historical_results_hash}-{historical_results_size}/"

Environment Variables

additional_environment

object

Environment variables to set for task execution. Values can be static or dynamic.Sources:

value - Static string
property - From action platform property
from_environment - From worker’s environment
timeout_millis - Task timeout in milliseconds
side_channel_file - Path for out-of-band communication
action_directory - Temporary directory for action (auto-cleaned)

additional_environment: {
  // Static value
  ENV_VAR: { value: "static-value" },
  
  // From action property
  POOL: { property: "pool" },
  
  // From worker environment
  PATH: "from_environment",
  
  // Task timeout
  TIMEOUT_MS: "timeout_millis",
  
  // Side channel for script communication
  SIDE_CHANNEL: "side_channel_file",
  
  // Temp directory
  ACTION_TMP: "action_directory"
}

Side channel file format (JSON):

{
  "failure": "timeout"  // Mark as timeout
}

Directory Cache

directory_cache

object

Caches reconstructed input directories using hardlinks to speed up repeated actions.

Show cache properties

max_entries

number

default:"1000"

Maximum cached directories.

max_size_bytes

number

default:"10737418240"

Maximum total cache size (bytes). Default: 10GB.

cache_root

string

Cache storage directory. Must be on same filesystem as work_directory. Defaults to {work_directory}/../directory_cache.

directory_cache: {
  max_entries: 5000,
  max_size_bytes: "50gb",
  cache_root: "/var/cache/nativelink/dircache"
}

Complete Example

{
  workers: [
    {
      local: {
        name: "worker-prod-1",
        
        worker_api_endpoint: {
          uri: "grpc://scheduler.internal:50061",
          timeout: 10
        },
        
        cas_fast_slow_store: "WORKER_FAST_SLOW",
        work_directory: "/mnt/nativelink/work",
        
        max_action_timeout: 3600,      // 1 hour
        max_upload_timeout: 600,       // 10 minutes
        max_inflight_tasks: 10,
        
        platform_properties: {
          cpu_count: { values: ["32"] },
          cpu_arch: { values: ["x86_64"] },
          cpu_vendor: { values: ["intel"] },
          memory_kb: { values: ["128000000"] },
          disk_read_iops: { values: ["10000"] },
          OSFamily: { values: ["Linux"] },
          "container-image": { values: [""] }
        },
        
        upload_action_result: {
          ac_store: "AC_MAIN",
          upload_ac_results_strategy: "success_only",
          failure_message_template: "https://ui.example.com/build/{action_digest_hash}"
        },
        
        additional_environment: {
          TMPDIR: "action_directory",
          TIMEOUT_MS: "timeout_millis",
          SIDE_CHANNEL: "side_channel_file"
        },
        
        directory_cache: {
          max_entries: 10000,
          max_size_bytes: "100gb"
        }
      }
    }
  ]
}

Configuration Reference

Examples

Worker Configuration

Worker Definition

Local Worker

Core Configuration

Platform Properties

Execution Settings

Result Upload

Environment Variables

Directory Cache

Complete Example

Build docs developers (and LLMs) love

Configuration Reference

Examples

​Worker Definition

​Local Worker

​Core Configuration

​Platform Properties

​Execution Settings

​Result Upload

​Environment Variables

​Directory Cache

​Complete Example

Build docs developers (and LLMs) love

Worker Definition

Local Worker

Core Configuration

Platform Properties

Execution Settings

Result Upload

Environment Variables

Directory Cache

Complete Example