Self-Hosted Runners

Configuring and using a self-hosted runner.

Self-hosted runners enable you to run pipelines on any infrastructure, including inside on-premise environments and behind firewalls. The runner is packaged as an executable that can be run as a service or as a Docker container.

Download Runner Agent

Download the runner executable from Sophos Factory:

  1. Go to your Account Settings page.
  2. Select Runners in the left navigation bar.
  3. Click the New Runner button and choose Self-Hosted.
  4. Enter a Name for your runner and optionally select the Projects you’d like to be able to use it.
  5. The modal will close and you’ll see your new runner among any other runners you may already have. Click on the new runner’s card, then click the Download Agent button.
  6. In the Runner Agent Version drop-down menu, several recent versions of the runner are available to choose. Generally, you will want to select the latest version. Click the Download button to download the runner TAR file, which looks something like: runner-agent_linux-x64_1.106.0-preview.tar.

Transfer the files to your desired runner machine and extract them. The archive also includes supporting library files, which must be placed in the same folder as the executable.

Install Runner

Self-hosted Sophos Factory runner agents can be deployed as a Docker container or using a virtual machine.

For guidance on both methods as well as example configuration files, see the Sophos Factory Runner Utilities repository.


Self-hosted runners require a unique identifier (AGENT_ID), as well as an authentication token (AGENT_KEY) to authenticate with the agent server.

AGENT_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 that are currently using the key until their configuration files are updated.

Changing the key requires restarting the runner agent.

Configure Runner

The runner agent requires a configuration file to start. 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.

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