taskcluster-worker takes a powerful configuration file on the form:

  - env
  - ... # Configuration transforms applied in order listed
  concurrency: 4
  ... # Configuration keys that will be transformed.

Once configuration transforms have been applied to the config section the final object must have a form that satisfies the schema in `config-schema.json'

credentialsObject of

The set of credentials that should be used by the worker when authenticating against taskcluster endpoints. This needs scopes for claiming tasks for the given workerType.


The security-sensitive access token for the client.

authorizedScopesArray of

The certificate for the client, if using temporary credentials.


ClientId for credentials

  • script
  • docker
  • mock
  • native
  • qemu

Selected worker engine to use, notice that the configuration for this engine must be present under the engines.<engine> configuration key.

enginesObject of

Mapping from engine name to engine configuration. Even-though the worker will only use one engine at any given time, the configuration file can hold configuration for all engines. Hence, you need only update the engine key to change which engine should be used.

dockerObject of

Path to the docker socket hosting the remote docker API.

If not given the default value unix:///var/run/docker.sock will be used.

  • always
  • allow
  • never

Allow task containers to run in privileged mode.

This option can take one of the 3 values:

  • always, run the task container in privileged mode regardless of what scopes the task in question has.
  • allow, the task container to run in privileged mode, if task.payload.privileged == true, and the task has the scope worker:privileged:<provisionerId>/<workerType>.
  • never, run task containers in privileged mode.

If in doubt use never and enable privileged mode when needed.

mockObject of
Anything ¯\_(ツ)_/¯
nativeObject of

Configuration for the native engine, this engines creates a system user-account per task, and deletes user-account when task is completed.


Tells if a system user should be created to run a command.

When set to true, a new user is created on-the-fly to run each task. It runs the command from within the users home directory. Iffalse`, the command runs without changing userid, hence, tasks will run with the same user as the worker does.

groupsArray of

List of system user-groups that the temporary task-users should be be granted membership of.

Group Namestring^[a-zA-Z0-9_.-]+$

Name of a user-group that task-users should be assigned

qemuObject of
limitsObject of

Limitations and default values for the virtual machine configuration. Tasks with machine images that does not satisfy these limitations will be resolved malformed-payload.


Number of CPU threads to assign, if assigning default values for threads, cores and sockets based on maxCPUs.

This should generally default to 2, if the host features hyperthreading, otherwise 1 is likely ideal.


Maximum number of CPUs a virtual machine can use.

This is the product of threads, cores and sockets as specified in the machine definition machine.json. If the virtual machine image does not specify CPU requires it will be given maxCPUs / defaultThreads number of cores in a single socket.


Maximum allowed virtual machine memory in MiB. This is also the default memory if the machine image does not specify memory requirements. If the machine specifies a memory higher than this, the task will fail to run.

machineObject of

Hardware definition for a virtual machine

  • pc-i440fx-2.8

CPU cores per socket, leave undefined to get maximum available

  • host

CPU to be exposed to the virtual machine.

The number of virtual CPUs inside the virtual machine will be threads * cores * sockets as configured below.

flagsArray of
  • VGA
  • vmware-svga
  • qxl-vga
  • virtio-vga
  • usb-kbd
  • PS/2
  • ar
  • da
  • de
  • de-ch
  • en-gb
  • en-us
  • es
  • et
  • fi
  • fo
  • fr
  • fr-be
  • fr-ca
  • fr-ch
  • hr
  • hu
  • is
  • it
  • ja
  • lt
  • lv
  • mk
  • nl
  • nl-be
  • no
  • pl
  • pt
  • pt-br
  • ru
  • sl
  • sv
  • th
  • tr

Local unicast MAC Address


Memory in MiB, defaults to maximum available, if not specified.

  • usb-mouse
  • PS/2
  • rtl8139
  • e1000

CPU sockets in machine, leave undefined to get maximum available

  • none
  • AC97
  • ES1370
  • hda-duplex/intel-hda
  • hda-micro/intel-hda
  • hda-output/intel-hda
  • hda-duplex/ich9-intel-hda
  • hda-micro/ich9-intel-hda
  • hda-output/ich9-intel-hda
  • virtio-blk-pci

Block device to use for attaching storage

  • usb-tablet
  • none

Threads per CPU core, leave undefined to get maximum available

  • piix3-usb-uhci
  • piix4-usb-uhci
  • nec-usb-xhci

System UUID for the virtual machine

  • 1
networkObject of
hostRecordsArray of
namesArray of
srvRecordsArray of

Number of subnets to creates. This determines the maximum number of concurrent VMs the worker can run.

Each subnet defines a set chains and rules in iptables, and thus, incurs some kernel overhead. It is recommended to create more subnets than needed, but to avoid creating the maximum unless required.

vpnConnectionsArray of

VPN Connections to be setup by the worker and exposed to the virtual machines, such that connections can be opened from the virtual machine to the routes exposed.

Note: servers on the VPN will not be able to open incoming connections to the virtual machines, as the VMs will sit behind NAT.


Client certificate as PEM encoded string.

This is the --cert argument for openvpn.


Certificate authority chain as one or more PEM encoded certificates.

This is the --ca argument for openvpn.

  • AES-128-CBC
  • AES-128-CFB
  • AES-128-CFB1
  • AES-128-CFB8
  • AES-128-GCM
  • AES-128-OFB
  • AES-192-CBC
  • AES-192-CFB
  • AES-192-CFB1
  • AES-192-CFB8
  • AES-192-GCM
  • AES-192-OFB
  • AES-256-CBC
  • AES-256-CFB
  • AES-256-CFB1
  • AES-256-CFB8
  • AES-256-GCM
  • AES-256-OFB
  • lzo
  • lz4
  • none

Compression algorithm to employ, if not given openvpn defaults to adaptive mode.


Private key matching the certificate as PEM encoded string.

This is the --key argument for openvpn.


Key direction for TLS, this is either 0 or 1, opposite of what the server is using.

This is the --key-direction argument for openvpn.

  • udp
  • tcp-client

Remote host running the VPN server.

This is the --remote argument for openvpn.


Require that server certificate is signed with the explicit extended key usage given here in oid notation.

This is the --remote-cert-eku argument for openvpn.


Time to renegotiation of data channel.

This is the --reneg-sec argument for openvpn.

routesArray of

Route to be exposed, this must be an IPv4 address.

This is the --route argument for openvpn.


TLS key as PEM encoded string.

This is the --tls-auth argument for openvpn.


Expected x509 name of remote server.

This is the first openvpn argument for --verify-x509-name.

  • name
  • name-prefix
  • subject

Type of the name given in x509Name.

This is the second openvpn argument for --verify-x509-name.

scriptObject of

Configuration properties for the 'scriptengine'.

commandArray of

Script and arguments to execute. This script will be fed a JSON string that matches the schema configured over stdin.

Output from the script over stdout will be uploaded as task log. Output from the script over stderr will be prefixed "[worker:error]" and merged with task log.

The script will be executed with a temporary folder as working directory, this folder can be used for temporary storage and will be cleared between tasks.

Files and folders stored in ./artifacts/ relative to the working directory will be uploaded as artifacts from the script. Hence, to make a public tar-ball artifact you create ./artifact/public/my-build.tar.gz which will be uploaded as an artifact named public/my-build.tar.gz.

Exit codes from the script will be intepreted as follows:

  • 0, task was executed successfully,
  • 1, task was executed but failed,
  • 2, task payload was not permitted, errors should be printed to stderr,
  • 3, script had a non-fatal error, task is resolved exception
  • 4, script had a fatal error, task is resolved exception, and the worker crashes.
schemaObject of

JSON schema for task.payload. A JSON string matching this schema will be piped to the script command over stdin.

propertiesObject of
Anything ¯\_(ツ)_/¯
requiredArray of
  • object

The minimum amount of disk space in bytes to have available before starting on the next task. Garbage collector will do a best-effort attempt at releasing resources to satisfy this limit.


The minimum amount of memory in bytes to have available before starting on the next task. Garbage collector will do a best-effort attempt at releasing resources to satisfy this limit.

monitorOne of
Object of

Use a mock implementation of the monitor that panics on errors.

  • mock
Object of
  • debug
  • info
  • warning
  • error
  • fatal
  • panic

Project name to be used in sentry and statsum


Name to use for process in syslog, leave as empty string to disable syslog forwarding.

tagsObject of

Tags that should be applied to all logs/sentry entries from this worker

pluginsObject of

Mapping from plugin name to plugin configuration. A plugin is enabled if it has an entry in this mapping, and isnt explicitly listed asdisabled. Even plugins that dont require configuration must have an entry, in these cases, empty object will suffice.

artifactsObject of

Configuration for artifact plugin. This is mostly COT (chain-of-trust) configuration, such as private key.


GPG armoured private key (unencrypted) for signing chain-of-trust certificates.

If not given, chain-of-trust signing will be disabled.

cacheObject of

Configuration for the cache plugin that manages sandbox caches.


The cache plugin will call the taskcluster-purge-cache service to fetch purge-cache requests, these are request that caches should be purged.

The cache plugin will pull the taskcluster-purge-cache service before every task to ensure that caches requested to be purged are not reused. However, if less than maxPurgeCacheDelay time have passed since the previous request to taskcluster-purge-cache then the request is skipped.

This defaults to 3 minutes, which is reasonable in most cases.


This is the baseUrl for the taskcluster-purge-cache service, which tells what caches should be purged.

This defaults to the production value from taskcluster-client libraries. You do not need to set this in production.

disabledArray of

List of disabled plugins. If a plugin is not listed as disabled here, even if its configuration key is present

  • maxruntime
  • success
  • env
  • livelog
  • logprefix
  • tcproxy
  • watchdog
  • artifacts
  • reboot
  • relengapi
  • tasklog
  • interactive
  • cache
envObject of
extraObject of

The extra property holds a mapping from variable name to value.

These extra environment variables will be injected into all tasks, though they can be overwritten on per-task basis using the task.payload.env property.

Notice that these overwrite built-in environment variables TASK_ID and RUN_ID which is also supplied by this plugin.

interactiveObject of

Configuration for the interactive plugin that allows user to configure tasks that expose an interactive shell or noVNC sessions.


If set the interactive plugin will be abled for all tasks.


Prefix that the sockets.json, display.html and shell.html should be created under. Defaults to private/interactive/.


If set the interactive display will be disabled.


If set the interactive shell will be disabled.


URL to a tool that can take display socket, list displays and render noVNC session. The URL will be given the querystring options: v=1, socketUrl, displaysUrl, taskId and runId.


Prevent tasks from specifying a custom artifactPrefix, by default tasks are allowed to overwrite the global setting.


URL to a tool that can take shell socket URL and display an interactive shell session. The URL will be given the querystring options: v=2, socketUrl, taskId, runId.

livelogObject of
Anything ¯\_(ツ)_/¯
logprefixObject of

Set of key-value pairs to be printed at the top of all tasks logs.

Note. values given here can overwrite built-in key-value pairs.

maxruntimeObject of

The maximum runtime plugin kills tasks that have a runtime exceeding the maxRunTime specified. This means it kills the sandbox and any interactive shells and display. Once killed the task will be resolved as failed.

This plugin only limits the time between execution start and end. That does not include artifact upload, download of images, etc. To guard against worker deadlocks use the watchdog plugin.

A maxRunTime limit is given in the plugin configuration, and the perTaskLimit option can be used to allow or require tasks to specify a shorter maxRunTime.


Maximum execution time before a task is killed, does not include artifact upload or image download time, etc.

  • require
  • allow
  • forbid

This plugin can forbid, allow or require tasks to specify task.payload.maxRunTime, which if present must be less than maxRunTime as configured at plugin level.

rebootObject of

The reboot plugin can be configured to stop the worker gracefully, or to allow tasks to stop the worker gracefully.

The reboot plugin assumes the worker is deployed in an environment where host machine reboots or resets if the worker exits. Hence, stopping gracefully is equivalent to rebooting the worker.

If this behaviour is not the case, the reboot plugin also allow configuration of an optional command to be executed when the worker is terminating due to a graceful shutdown initiated by the reboot plugin.


Allow tasks to specify a task.payload.reboot that specifies if the worker should reboot after the task finishes.

Tasks can specify task.payload.reboot as "always", "on-failure" and "on-exception", the property is always optional.


Maximum amount of time before gracefully shutting down the worker.

Given as integer in seconds or as string on the form: 1 day 2 hours 3 minutes. Leave the value as zero or empty string to disable worker life-cycle limitation.

rebootCommandArray of

Command to run when the worker is stopping, if the reboot plugin caused the worker to stop.

It is recommended that the worker is launched by a start-up script that reboots/resets the system and lunches the worker again, when the worker exits. This is a fairly robust behavior on most deployment scenarios.

However, there may be cases where its desirable to change behavior depending on whether or not it is thereboot` plugin that stops the worker. In these cases this optional command can be useful.

The command is executed when the worker is stopping, if the reboot plugin initiated the worker shutdown. The command will be executed after all tasks have finished as part of the clean-up process, hence, one can specify ["sudo", "reboot"] and expect a graceful reboot.


Maximum number of tasks to process before gracefully shutting down the worker.

Defaults to zero implying no limitation. This is mainly useful as taskLimit: 1 to reboot between each task. Or if running tests and you want to stop the worker after one task.

relengapiObject of

The relengapi proxy provide access to the Releng API.


The releng API base domain. Default:


The issue token to use. This token is used to retrieve a temporary token that is used to make requests to the endpoint.

successObject of
Anything ¯\_(ツ)_/¯
tasklogObject of
Anything ¯\_(ツ)_/¯
tcproxyObject of
Anything ¯\_(ツ)_/¯
watchdogObject of

The watchdog plugin resets a timer whenever the worker is reported as idle or processes a step in a task. This ensure that the task-processing loop remains alive. If the timeout is exceeded, the watchdog will report to sentry and shutdown the worker immediately.

This plugin is mainly useful to avoid stale workers cut in some livelock. Note: This plugin wont cause a timeout betweenStarted()andStopped(), as this would limit task run time, for this purpose use themaxruntime` plugin.


Timeout after which to kill the worker, timeout is reset whenever a task progresses, worker is reported idle or task is between Started() and Stopped().

Defaults to 45 minutes, if not specified (or zero). This is a sound value, lower than 30 minutes is not recommended as plugins will be reported as stalled, if a hook takes longer than 30 minutes, and such error reports contains more context.

This property is specified in seconds as integer or as string on the form 1 day 2 hours 3 minutes.


Path to folder that can be used for temporary files and folders, if folder doesn`t exist it will be created, otherwise it will be overwritten.

webHookServerOne of
Object of
  • localhost
Object of
  • localtunnel
Object of

Used to limit the time period for which the DNS server will return an IP for the given worker hostname.

This should be larger than the maximum task runtime. If not set it`ll default to 1 day, which is sane for most use-cases.


Port webhookserver should listen on. If not supplied, it uses the serverPort value.


Network device webhookserver should listen on. If not supplied, it binds to the interface from serverIp address

  • stateless-dns
Object of
  • webhooktunnel
workerObject of

Configuration for the worker


The number of tasks that this worker supports running in parallel.


If superseding is enabled, tasks can specify a URL that returns a list of taskIds that supersedes the given task.

For details see superseding documentation.


Minimum number of seconds to wait before reclaiming a task. it is important that this is some reasonable non-zero minimum to avoid overloading servers if there is some error.


The amount of time to wait between task polling iterations in seconds.


ProvisionerId for workerType that tasks should be claimed from. Note, a workerType is only unique given the provisionerId.


The number of seconds prior to task claim expiration the claim should be reclamed.


Group of workers this machine belongs to. This is any identifier such that workerGroup and workerId uniquely identifies this machine.


Identifier for this machine. This is any identifier such that workerGroup and workerId uniquely identifies this machine.


WorkerType to claim tasks for, combined with provisionerId this identifies the pool of workers the machine belongs to.

Transform abs

Transform env

Transform hostcredentials

Transform packet

Transform secrets