Machine runner configuration reference

Server v4.0 - v4.6

Machine runner configuration reference

A YAML file is used to configure the machine runner, how it communicates with CircleCI’s servers, and how it will launch the task-agent.

The configuration file uses the following format with the various parameters explained in more detail below:

api:
  auth_token: AUTH_TOKEN
runner:
  name: RUNNER_NAME

Machine runner can also be configured via environment variables. These will be prioritized over the YAML file, if set.

`api.auth_token`

$LAUNCH_AGENT_API_AUTH_TOKEN

A token used to identify the machine runner to CircleCI and can be generated by the CircleCI CLI. An existing token may be shared among many installations, but this token only allows a particular resource_class to be specified.

`api.url`

$LAUNCH_AGENT_API_URL

A fully qualified URL used by self-hosted runners to communicate with CircleCI. This variable is only required for self-hosted runners installed for the 3.2 or later version of server.

Example:

api:
  url: https://circleci.example.com

`runner.name`

$LAUNCH_AGENT_RUNNER_NAME

RUNNER_NAME is a unique name of your choosing assigned to this particular machine runner. CircleCI recommends using the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the UI on the CircleCI web app. The only special characters accepted in RUNNER_NAME are . () - _.

`logging.file`

$LAUNCH_AGENT_LOGGING_FILE

This controls the file where the machine runner launch-agent and task-agent logs will go. See CircleCI concepts for more information on launch-agents and task-agents.

Example:

logging:
  file: /Library/Logs/com.circleci.runner.log

`runner.command_prefix`

$LAUNCH_AGENT_RUNNER_COMMAND_PREFIX

This prefix takes a YAML list of arguments that wraps and runs the task-agent.

For example, sudo can elevate permissions:

runner:
  command_prefix: ["sudo", "-niHu", "USERNAME", "--"]

The prefix can also be a custom script. The arguments passed to the script will launch the task-agent.

The custom script must:

Take great care to ensure the task-agent (that is, the arguments passed to it) runs
Forward the exit code from task-agent as its own exit code

Example script saved as /var/opt/circleci/wrapper.sh:

#!/bin/bash

task_agent_cmd=${@:1}
echo "About to run CircleCI task agent: ${task_agent_cmd}"
$task_agent_cmd
exit=$?
echo "CircleCI task agent finished."
exit $exit

Config snippet for above example:

runner:
  command_prefix: ["/var/opt/circleci/wrapper.sh"]

`runner.working_directory`

$LAUNCH_AGENT_RUNNER_WORK_DIR

This directory takes a fully qualified path and allows you to control the default working directory used by each job. If the directory already exists, the task-agent will need permissions to write to the directory. If the directory does not exist, then the task-agent will need permissions to create the directory.

These directories will not automatically be removed, see cleanup_working_directory to configure cleanup of directory.

Example:

runner:
  working_directory: /var/opt/circleci/workdir

`runner.cleanup_working_directory`

$LAUNCH_AGENT_RUNNER_CLEANUP_WORK_DIR

CircleCI recommends using a knowable directory, however it is possible to specify %s in the path. This value will be replaced with a different value for each job. This is a substitution that is only knowable at job runtime, under the environment variable $CIRCLE_WORKING_DIRECTORY.

Example:

runner:
  working_directory: /var/opt/circleci/%s

$LAUNCH_AGENT_RUNNER_CLEANUP_WORK_DIR

This flag enables you to control the working directory cleanup after each job.

The possible values are:

true
false

The default value is false.

Example:

runner:
  cleanup_working_directory: true

`runner.mode`

$LAUNCH_AGENT_RUNNER_MODE

This parameter allows you to specify whether you want to terminate this self-hosted runner instance upon completion of a job (single-task), or to continuously poll for new available jobs (continuous).

The possible values are:

continuous
single-task

The default value is continuous.

Example:

runner:
  mode: continuous

`runner.max_run_time`

$LAUNCH_AGENT_RUNNER_MAX_RUN_TIME

This value can be used to override the default maximum duration the task-agent will run each job. Note that the value is a string with the following unit identifiers h, m or s for hour, minute, and seconds respectively:

Here are a few valid examples:

72h - 3 days
1h30m - 1 hour 30 minutes
30s - 30 seconds
50m - 50 minutes
1h30m20s - An overly specific (yet still valid) duration

The default value is 5 hours.

Example:

runner:
  max_run_time: 5h

Customizing job timeouts and drain timeouts

If you would like to customize the job timeout setting, you can “drain” the job by sending the machine runner a termination (TERM) signal, which then causes the machine runner to attempt to gracefully shutdown. When this TERM signal is received, the machine runner enters “draining” mode, preventing the machine runner from accepting any new jobs, but still allowing any current active job to be completed. At the end of “draining,” the machine runner then signals the task-agent to cancel any active job (by sending it a TERM signal).

If the task-agent does not exit a brief period after the TERM, the machine runner will manually kill it by sending it a KILL signal.

Draining can end in one of two ways:

The task has been in the draining state for longer than the configured max_run_time
An additional TERM signal is received by the machine runner during “draining”

`runner.idle_timeout`

$LAUNCH_AGENT_RUNNER_IDLE_TIMEOUT

This timeout will enable a machine runner to terminate if no task has been claimed within the given time period. The value is a string with the following unit identifiers: h, m or s for hours, minutes, and seconds respectively (for example, 5m is 5 minutes).

The default behaviour is to never time out due to inactivity.

Example:

runner:
  idle_timeout: 1h

`runner.disable_auto_update`

$LAUNCH_AGENT_RUNNER_DISABLE_AUTO_UPDATE

This parameter will disable launch-agent from attempting to automatically update itself, and stop making requests to CircleCI to check for new versions. This parameter is recommended to be set to true on server installations where version pinning is used.

Note: Setting this parameter will require self-hosted runner installations to be manually upgraded to receive new features, security updates, and bug fixes.

`runner.ssh.advertise_addr`

$LAUNCH_AGENT_RUNNER_SSH_ADVERTISE_ADDR

This parameter enables the “Rerun job with SSH” feature. Before enabling this feature, there are important considerations that should be made. Rerun with SSH is not currently available on container runner.

The address is of the form host:port and is displayed in the “Enable SSH” and “Wait for SSH” sections for a job that is rerun.

While the presence of the runner.ssh.advertise_addr variable enables the “Rerun job with SSH” feature, the value it holds is for publishing purposes only in the web app. The address does not need to match the actual host and port of the machine that the self-hosted runner is installed on, and can be a proxy configuration.

Example:

runner:
  ssh:
    advertise_addr: HOSTNAME:54782

Considerations before enabling SSH debugging

Task-agent runs an embedded SSH server and agent on a dedicated port when the “Rerun job with SSH” option is activated. This feature will not affect any other SSH servers or agents on the system that the self-hosted runner is installed on.

The host port used by the SSH server is currently fixed to 54782. Ensure this port is unblocked and available for SSH connections. A port conflict can occur if multiple machine runners are installed on the same host.
The SSH server will inherit the same user privileges and associated access authorizations as the task-agent, defined by the runner.command_prefix parameter.
The SSH server is configured for public key authentication. Anyone with permission to initiate a job can rerun it with SSH. However, only the user who initiated the rerun will have their SSH public keys added to the server for the duration of the SSH session.
Rerunning a job with SSH will hold the job open for two hours if a connection is made to the SSH server, or ten minutes if no connection is made, unless cancelled. While in this state, the job is counted against an organization’s concurrency limit, and the task-agent will be unavailable to handle other jobs. Therefore, it is recommended to cancel an SSH rerun job explicitly (through the web UI or CLI) when finished debugging.

Basic full configuration for a machine runner

The fields you must set for a specific job to run using your self-hosted runners are:

machine: true
resource_class: <namespace>/<resource-class>

Simple example of how you could set up a job:

version: 2.1

workflows:
  build-workflow:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - run: echo "Hi I'm on Runners!"

The job will then execute using your self-hosted runner when you push the config to your VCS provider.

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site

Machine runner configuration reference

On This Page