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, Torq 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:
Enter a name that reflects the Runner's type (Kubernetes or Docker) and the deployment environment.
Enter a meaningful description to provide context.
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.
Specify a Step Runner for Step Execution
To use a Step Runner for specific Steps:
Add the Step to your workflow canvas.
Open the Execution Options section.
Select the Step Runner from the Runner dropdown.
Regenerate an Install Command
To reinstall an unhealthy Runner or deploy an additional instance:
Go to Integrations > Step Runner and select the desired Runner.
Click the More Options menu to choose Regenerate install command.
Select the deployment platform: Docker or Kubernetes.
Copy the new install command and execute it 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.
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 |
Used to pull the runner image | |
Used to pull configurations (one time) | |
| Used to communicate with the Torq service |
Used to upload logs | |
Used for authentication |
For a complete list of IP addresses used by Google, refer to:
Proxy Support
Background
Step Runners communicate with the Torq service via an outbound gRPC-over-TLS connection—that is, we use a TLS transport to carry gRPC instructions. Additional operations (such as uploading logs and downloading images) are performed via outbound HTTPS connections.
This communication may be configured to operate through a proxy server. Follow the instructions below for details on how to customize your Step Runner deployment.
Note:
Torq strongly recommends against performing SSL or TLS inspection (commonly known as "man-in-the-middle" inspection) for the communication with the Torq service. The primary reasons for this are:
The communication uses an application-layer encrypted non-web protocol. The inspection engine may not support inspecting the traffic, and may interfere with communications.
The traffic is binary and mostly encrypted at the application level, so the inspection won’t find anything.
It weakening our security—we cannot verify the client certificate from the runner connections.
It wastes the inspecting proxy’s CPU power and slows things down.
For customers who have implemented SSL or TLS inspection, Torq strongly recommends that the Torq service communication be excluded from this inspection layer.
Deployment in Various Environments
Self-hosted step runners can be deployed in a variety of additional environments, including:
Advanced Deployment Settings
Customize Deployment Instructions