Self-Hosted Runner Pools

Configuring and using self-hosted Runner Pools.

Self-hosted Runner Pools enable you to provision Runners to run pipelines on any infrastructure, including inside on-premise environments and behind firewalls. The Runner Pool is packaged as an executable that can be can be deployed in a container or Virtual Machine (VM).


Self-hosted Runner Pools require a unique identifier (RUNNER_MANAGER_ID), as well as an authentication token (RUNNER_MANAGER_KEY) to authenticate with the agent server.

RUNNER_MANAGER_KEY is similar to a password, and should be stored securely. It can also be regenerated from Sophos Factory, which will immediately invalidate any runners, or runner pools that are currently using the key until their configuration files are updated.

Changing the key requires a re-deployment of the Runner Pool.

Deploying the Runner Pool

Configuring Runner Pool

The Runner Pool requires configuration for both authenitcation, as well as the provider which is used for provisioning runners.

  "ENVIRONMENT": "The name of your environment. Our pre-built helm chart defaults this to `prod`",
  "RUNNER_MANAGER_KEY": "The secure password used to authenticate with Sophos Factory.",
  "RUNNER_MANAGER_ID": "The unique identifier of the Runner Pool.",

CloudFormation Provider Configuration

    "RUNNER_EC2_IMAGE_REGION": "The AWS region where the AMI is located.",
    "RUNNER_EC2_INSTANCE_TYPE": "The AWS EC2 Instance Type to deploy.",
    "RUNNER_EC2_SUBNETS": "An array of AWS VPC subnet ID strings.",
    "RUNNER_EC2_SECURITY_GROUP_ID": "The security group ID to apply to the EC2 VM.",
    "RUNNER_EC2_IMAGE_ACCOUNT_ID": "The AWS account number where the AMI is located. Default is 835705546860",
    "RUNNER_EC2_IMAGE_PREFIX": "AMI image prefix used to search for Runner AMIs. Defaults to factory_runner_x64_centos8_2.0.*_*ENV*_",
    "RUNNER_EC2_AUTOLATEST": "If true, automatically uses latest Runner AMI.",

Kubernetes Provider Configuration

    "RUNNER_K8S_IMAGE_REGISTRY": "Location of the container registry. Defaults to",
    "RUNNER_K8S_IMAGE_REPOSITORY": "Name of container repository. Defaults to sophos/fac-runner",
    "RUNNER_K8S_IMAGE_TAG": "Container tag to use. Defaults to latest",
    "RUNNER_K8S_NAMESPACE": "Namespace to deploy Runners to. Defaults to `${ prefix }-${ env }-runner`",
    "RUNNER_K8S_CPU_REQUEST": "CPU units to request for Runner pod.",
    "RUNNER_K8S_CPU_LIMIT": "CPU units to limit Runner pod to.",
    "RUNNER_K8S_MEM_REQUEST": "Memory units to request for Runner pod.",
    "RUNNER_K8S_MEM_LIMIT": "Memory units to limit for Runner Pod."

Customizing Runner

A runner may be customized by extending our Runner Containers/AMIs, or by downloading the binary and building your own.

Runner Configuration

Runner customization can be achieved by overriding configuration. By default, it will look for the configuration file in /etc/runner-agent.json. You may also specify the path to the configuration file by setting the CONFIG_PATH environment variable.

Below is an example runner configuration file with all possible fields and their default values. All of these fields are optional except AGENT_ID and AGENT_KEY, which the Runner Pool injects at deploy time via environment variables.

  "AGENT_ID": "<enter your agent id here>",
  "AGENT_KEY": "<enter your agent key here>",
  "LOG_PATH": "/var/log/runner-agent",
  "LOG_FILENAME_PATTERN": "runner-agent-%DATE%.log",
  "LOG_LEVEL": "info",
  "WORKSPACE_PATH": "/opt/runner-agent/workspace"
  • AGENT_ID: Unique identifier for the runner. This value is retrieved from Sophos Factory.
  • AGENT_KEY: Authentication key for the runner. This value is retrieved from Sophos Factory.
  • LOG_PATH: Path to the directory where log files will be written.
  • LOG_FILENAME_PATTERN: If LOG_PATH is provided, specifies the log file naming pattern. Occurences of %DATE% will be replaced with the current date in YYYY-MM-DD format.
  • LOG_RETENTION: The retention duration for log files. If a number is provided, this is the maximum number of log files. If a string ending in d is provided, such as 20d, this is the number of days before log files are deleted.
  • LOG_LEVEL: The verbosity of log output. Valid values are info, warning, debug, or error.
  • WORKSPACE_PATH: Path to the root of the runner workspace. Pipeline run directories will be created within this directory.

You can find configuration examples in the Sophos Factory Runner Utilities repository.