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:
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
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.
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 theListenStream
parameter is listed.[Socket]
ListenStream=%t/podman/podman.sock
SocketMode=0660Enable 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 theremoteSocket
is listed.remoteSocket:
exists: true
path: /run/podman/podman.sockExecute 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 andDOCKER_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 thatMounts
matches theremoteSocket
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.