Skip to content
Docs
Cancel

Self-hosted Runner Configuration reference

Last updated
Tags Cloud Server v3.x

Self-hosted runner configuration reference

A YAML file is used to configure the launch agent, how it communicates with our 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
The launch agent 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

This is a token used to identify the launch agent 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

This is 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 assigned to this particular running launch agent. 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 CircleCI UI.

logging.file

$LAUNCH_AGENT_LOGGING_FILE

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

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:

  1. Take great care to ensure the task agent (that is, the arguments passed to it) runs

  2. Forward the exit code from task agent as its own exit code

Example script saved as /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: ["/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. If installing multiple launch-agents on the same machine, each launch-agent will need a unique working directory.

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

Example:

runner:
  working_directory: /opt/circleci/workdir

runner.cleanup_working_directory

CircleCI recommends using a knowable directory, however it is possbile 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: /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 launch agent a termination (TERM) signal, which then causes the launch agent to attempt to gracefully shutdown. When this TERM signal is received, the launch agent enters “draining” mode, preventing the launch agent from accepting any new jobs, but still allowing any current active job to be completed. At the end of “draining,” the launch agent 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 launch agent 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 launch agent during “draining”

runner.idle_timeout

$LAUNCH_AGENT_RUNNER_IDLE_TIMEOUT

This timeout will enable a launch agent 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 (e.g., 5m is 5 minutes).

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

Example:

runner:
  idle_timeout: 1h

runner.disable_auto_update

$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.

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 UI. 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 launch agents 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 self-hosted runners

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

  • machine: true

  • resource_class: your-namespace/your-resource

Here is a simple example of how you could set up a job:

version: 2.1
workflows:
  testing:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: your-namespace/your-resource
    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.


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams