Use self-hosted Step Runners to execute workflow steps that require access to services within your private environments, such as virtual private clouds (VPCs) or on-prem data centers. By default, steps run on the Torq Cloud Runner, but steps requiring access to private resources must be executed on a self-hosted Runner.

Configure a self-hosted Step Runner

It is recommended to allocate at least 2GB RAM and 2 vCPUs for Step Runners. In Kubernetes, these resources should be allocated to the nodes hosting the Runner and, in Docker, to the host machine.

Before deploying a self-hosted Step Runner, ensure the machine has sufficient memory and the correct configurations to meet workload demands.

Supported architectures

Torq's container images are compiled for x86_64 (Intel/AMD) architectures and are supported on compatible platforms with common distributions—including Debian-based (e.g. Ubuntu, Mint), Red Hat–based (e.g. Fedora, CentOS), Arch-based (e.g. Manjaro), and independent or specialized (e.g. Gentoo) distributions—that serve as the foundation for container technologies like Docker, Podman, and Kubernetes. Supported architectures may include physical hosts, virtual machines, or cloud platforms such as AWS EC2, GCE, and Azure VM.

Torq's Step Runners can be deployed on managed Kubernetes services (e.g. AKS, EKS), but are not currently supported on managed container services (e.g. ECS, ACI).

Deploy a Docker or Kubernetes (K8s) Step Runner

To create and deploy a self-hosted Step Runner:

Navigate to the Step Runner: In Torq, go to Integrations > Runner and click Add Instance.
Configure the Step Runner:
1. Enter a name that reflects the Runner's type (Kubernetes or Docker) and the deployment environment.
2. Enter a meaningful description to provide context.
3. Select Kubernetes or Docker.
Copy the install command: Click Add and copy the install command that is generated.
Execute the install command: Paste the install command in your terminal. This deploys the Step Runner using the generated YAML configuration file that is automatically downloaded to your device.
Confirm the installation: Return to the Step Runner page and verify that the Runner's status has changed from Pending to Healthy.
- For each Runner, you can see its creation time, creator, status, description, type (Kubernetes or Docker), and version.

The install command for the Runner is valid for 24 hours. If needed, you can regenerate a new install command.

URLs required for communication with Torq

To ensure proper functionality, verify that the host where the Step Runner is deployed has access to the following URLs:

URL	Purpose
https://us-docker.pkg.dev/	Used to pull the runner image
https://link.torq.io/ or https://link.eu.torq.io/	Used to pull configurations (one time)
https://pubsub.googleapis.com/	Used to communicate with the Torq service
https://storage.googleapis.com/ https://storage.torq.io/ or https://storage.eu.torq.io	Used to upload logs
https://auth.googleapis.com/ https://oauth2.googleapis.com/ https://logging.googleapis.com	Used for authentication
http://api.ipify.org/	Used to identify the Step Runner's public IP
http://cloud.google.com/	Used to check connectivity

For a complete list of IP addresses used by Google, refer to:

Specify a Step Runner for Step execution

To use a Step Runner for specific steps:

Open a workflow: Go to Build > Workflows and open the relevant workflow.
Add a step: Drag a step to the workflow canvas.
Select a Step Runner: In the Properties tab, open the Execution Options section and choose a Runner.

Deploy an additional Runner instance

For scaling and load-sharing in a Kubernetes deployment, it is recommended to add replicas to spec in the deployment configuration file rather than regenerate the install command in Torq.

To deploy an additional Runner instance:

Navigate to the Step Runner: Go to the Step Runner page and select the desired Runner.
Regenerate the command: Click the More Options menu and select Regenerate install command.
Specify the deployment type: Select Docker or Kubernetes.
Execute the command: Copy the new install command and execute it in a host within 24 hours.

Monitor Step Runner health

Torq provides a built-in diagnostic collector that reports on the health and performance of self-hosted Step Runners. The collected data includes the Runner’s URL connectivity and resource capacity (CPU, memory, disk space). The minimum version requirement for diagnostics is v25.06.4.

Diagnostic data is reported every two minutes.

Unless you have custom values, you will see an alert by default when the Runner's:

CPU is above 80%
Memory is above 80%
Disk space usage is above 1 GB (Docker only)

To proactively monitor the health of your Step Runners:

Navigate to the Step Runner: Go to Build > Integrations and select Step Runner.
Check the diagnostics: In the Status Details column, click Show Diagnostics.

Update a Docker or Kubernetes (K8s) Step Runner

You can update the settings or upgrade the version of Docker and Kubernetes Step Runners.

For Docker-based deployments:

Terminate the existing container and instantiate a new one with the appropriate configuration changes.
If the installation script was saved or pulled from the Docker host's history, update it.
Alternatively, you can deploy an additional Runner instance or customize a new deployment configuration file.

For Kubernetes-based deployments:

Adjust the deployment configuration file and redeploy the Runner.
If the file is not readily available, you can deploy an additional Runner instance or customize a new deployment configuration file.

Deploy Docker Step Runners on Podman

Red Hat Enterprise Linux (RHEL), CentOS, and Oracle Linux are now shipping with Podman instead of Docker. While similar, there are significant structural and architectural differences between Podman and Docker.

To deploy Docker Step Runners on Podman:

Check the socket's configuration: Run the command
cat /usr/lib/systemd/system/podman.socket to verify that the ListenStream parameter is listed.
```
[Socket] 
ListenStream=%t/podman/podman.sock 
SocketMode=0660
```
Enable and start the socket: Run the command
systemctl enable --now podman.socket to enable and immediately start the socket.
Check the Podman environment's configuration: Run podman info to verify that the remoteSocket is listed.
```
remoteSocket:
  exists: true
  path: /run/podman/podman.sock
```
Execute the install command: Retrieve the Docker install command from Torq and paste it in your terminal without the | sh.
Copy the output: Copy the command output and paste it into a new line or an editor.

Edit the output: Replace the docker references with Podman-specific references, including the --privileged flag and DOCKER_HOST environment reference.

docker run -d --restart always -v /var/run/docker.sock:/var/run/docker.sock --log-driver=json-file --log-opt max-size=10m --log-opt max-file=10 -e ENCODED_GCLOUD_CREDS...

# becomes

podman run -d --restart always -v /run/podman/podman.sock:/run/podman/podman.sock -e DOCKER_HOST=unix:///run/podman/podman.sock --privileged
--log-driver=json-file --log-opt max-size=10m --log-opt max-file=10 -e ENCODED_GCLOUD_CREDS...

Start the Runner: Run the edited output above to start the Runner.
Check the Runner's status: Either check the Runner's status from the Step Runner page in Torq, or run podman ps in the Terminal.
Check the socket's configuration: Run the command curl --unix-socket /run/podman/podman.sock -H 'content-type: application/json' -sf http://localhost/containers/json | jq to verify that Mounts matches the remoteSocket path from earlier.
```
"Mounts": [
  {
    "Type": "bind",
    "Source": "/run/podman/podman.sock",
    "Destination": "/run/podman/podman.sock",
```

If the user running curl doesn't have permissions or the container isn't running, the command will return either [] or no data.

Deploy Docker Step Runners on K3S

To deploy Docker Step Runners on Rancher K3S, follow standard K8s deployment practices.

Deploy Self-hosted Step Runners on AWS Elastic Kubernetes Service (EKS)

Explore Torq Steps: Workflow Building Blocks

Troubleshoot Self-hosted Step Runners

Deploy Self-hosted Step Runners on Microsoft Azure Kubernetes Service (AKS)

Customize Self-hosted Step Runners: Advanced Deployment Settings