You can create a custom container to use inside Torq as a step. This guide assumes basic familiarity with Docker containers and Docker Hub.

A custom container step consists of two components: a Dockerfile, which defines how the container is built, and an entrypoint script, which gathers the environment variables passed to the container, executes the step's function, and optionally normalizes the output data to JSON.

Dockerfile

Start with the Dockerfile and choose a base image. Keep the container as small as possible to minimize execution time, Alpine Linux (~5MB) is a good starting point. The example below from the torq-step-example repo defines the alpine:latest image, copies the entrypoint.sh file, and installs the curl utility using apk:

FROM alpine:latest
COPY entrypoint.sh /entrypoint.sh
RUN  apk update \
   && apk add curl \
   && chmod +x entrypoint.sh
ENTRYPOINT ["/bin/ash","entrypoint.sh"]

Entrypoint script

The entrypoint script controls the step's input, output, and signaling. Input parameters defined in the step are passed to the container as environment variables, which the script reads and uses accordingly.

Output should be JSON-formatted for compatibility with the Torq ecosystem. Use jq or similar utilities to convert non-JSON output when needed.

For signaling, use exit 0 on success and exit 9 on failure. This determines whether the step displays a green checkmark or an error in the workflow.

The example below checks for the COMMAND input parameter, outputs a JSON response, and exits with the appropriate code. Note that the variable name (COMMAND) matches the parameter name in the Torq UI:

if [ -z "$COMMAND" ] # Check if the required parameter is passed.
then
    echo "{\"error\":\"no command provided\"}"
    exit 9
else
    echo "{\"command\":\"your command is $COMMAND\"}"
    exit 0
fi

Build and test the container

Once the Dockerfile and entrypoint script are in the same directory, build the container. All Torq steps require the platform to be set to linux/amd64:

docker build -t example . --platform=linux/amd64

Test the container locally by passing environment variables with --env to emulate how Torq passes parameters at execution:

docker run -it --rm --name example --env COMMAND="such command, much wow!"

A successful run produces JSON-formatted output:

{"output": "Hello There. Your command is, such command, much wow!.\n"}

Once tested, push the image to Docker Hub. Each change to the container requires an incremented tag version, which maps directly to the step version in Torq:

docker tag example yourdockerhub/example:1.0.0
docker push yourdockerhub/example:1.0.0

Step YAML

Each step in Torq is defined in YAML. To configure your custom container as a step:

Add a Send HTTP Request step: Drag the step onto the workflow Canvas.
Rename the step: Give it a name that reflects its function.

Open the YAML editor: Select Edit YAML from the step three-dot menu (...).

manifestId: c8beae5b-78e4-4401-b6b8-7cbfb534b88a
name: us-docker.pkg.dev/stackpulse/public/http/request:4.2.3
id: send_an_http_request
isPrivate: false
icon: ""
env:
  URL: ""
  METHOD: GET
  AUTHORIZATION: None
  HEADERS: ""
pretty_name: Send an HTTP request

Remove the manifestId line: Delete it from the YAML.
Update the name field: Set it to the location of your Docker Hub image. In this example, the repo is helloworld with tag version 1.0.0 inside the joeattorq Docker Hub account, resulting in joeattorq/helloworld:1.0.0.
Update the env field: List the input parameters to pass to the container at execution. Each key is the name of the environment variable the container reads from. Note the indentation, in this example, there is one parameter (COMMAND), so only one entry is listed under env.

Update optional fields: Set icon and documentationUrl for additional customization.
Your YAML should look something like this:

name: joeattorq/helloworld:1.0.0
id: hello_world
documentationUrl: https://knowyourmeme.com/memes/doge
icon: https://raw.githubusercontent.com/joe-at-torq/Torq-Steps/main/Icons/cool-doge.png
env:
  COMMAND: such command, much wow!
pretty_name: Hello World
isPrivate: false

Save the configuration: Once saved, your new step and its parameters will appear on the workflow Canvas.

Explore Torq Steps: Workflow Building Blocks

Encoding Utilities

Deploy Self-Hosted Step Runners

Troubleshoot Self-Hosted Step Runners

Customize Self-Hosted Step Runners: Advanced Deployment Settings

Build a Custom Container Step

Dockerfile

Entrypoint script

Build and test the container

Step YAML