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 the host running a Step Runner. 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 Step Runner

To access the Step Runner deployment wizard, go to Integrations > Step Runner to reach the Step Runners page. The Create step runner, Retrieve a step runner, and Regenerate a step runner install command steps are available on this page.

Make sure to properly install and configure Podman prior to deploying Podman Step Runners. The install command generated by the wizard is configured for a privileged installation. If deploying on a non-root installation, follow the specific non-root instructions.

To create and deploy a self-hosted Step Runner:

Navigate to the Step Runner: In Torq, go to Integrations > Step Runners and click Add Step Runner.
Configure the Runner details:
1. Enter a unique name.
2. Enter a meaningful description to provide context.
3. Select Kubernetes, Docker, or Podman.
4. For Kubernetes and Docker Runners, select whether to run as root or non-root (for version 26.03.8 or above). For Podman, follow the specific non-root instructions.
5. Click Next.
(Optional) Configure the Runner setup:
1. Select whether to use Torq's managed container registry or a private registry to pull container images.
2. Specify values of relevant parameters to override the default Runner settings, such as CPU or memory limits.
3. Specify whether to apply a label in key-value pair form to K8s jobs and the pod template spec.
4. Click Next.
Generate the install command: Click Generate install command and copy the command.
Execute the install command: Paste the install command in your terminal. This deploys the Step Runner using the generated Docker docker run command or Kubernetes YAML configuration file that is automatically downloaded to your device.
1. For Podman, update the installation command by replacing --privileged with --userns=keep-id --security-opt label=disable.
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, Docker, or Podman), and version.
- For Podman runners, check the socket's configuration by running 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", 
```

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
https://api.ipify.org/	Used to identify the Step Runner's public IP
https://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 Podman Step Runners

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 Step Runners on Podman:

Install Podman: Run the command sudo dnf install podman or follow standard installation best practices.
1. When running as non-root, verify that cgroup controllers for cpu cpuset io memory pids are delegated and follow Podman's recommendations for non-root setup. In particular, the following:
```
sudo sysctl -w user.max_user_namespaces=28633
echo "user.max_user_namespaces=28633" | sudo tee /etc/sysctl.d/99-userns.conf
sudo usermod --add-subuids 100000-165535 <service account>
sudo usermod --add-subgids 100000-165535 <service account>
```
Activate the remote socket: Run the command systemctl --user start podman.socket to activate the socket prior to deployment.
Ensure user session persistence: Run the command sudo loginctl enable-linger <service account> to keep containers running after sessions end.
Ensure container lifecycle management: Make sure containers run as a systemd (Podman <4.4) or Quadlet service.
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
```
Deploy the Runner: Follow the instructions in the Deploy a Step Runner section of this guide.

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

Deploy Step Runners on K3S

To deploy Docker Step Runners on K3S (the lightweight version of Kubernetes), follow standard K8s deployment practices.

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

Troubleshoot Self-Hosted Step Runners

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

Customize Self-Hosted Step Runners: Advanced Deployment Settings

Share Step Runners Across Torq Workspaces