Installing a Runner

Traceable runners are designed to operate across various infrastructure and deployment setups. A well-prepared system is essential to ensure stable operation, consistent scan execution, and predictable performance as environments grow and evolve.

What will you learn in this topic?

By the end of this topic, you will understand:

The prerequisites for installing a runner.
The various methods for installing a runner, along with the corresponding steps.
The concept of runner labels and how you can use them

Before you begin

Make a note of the following before proceeding with setting up Runner:

You must have the necessary software and hardware requirements for the runner to perform efficiently. For more information, see Software and Hardware Requirements.
Ensure that the machine where you are installing the Runner can communicate with the APIs and Traceable Platform.
DAST does not need an app to be instrumented, but an environment still needs to be created for DAST scan to create a default service and list APIs under it.
Runners are not scoped by the environment. They are available for all environments.
Ensure you are assigned the Security admin or Account Owner role, or the corresponding permissions to start a runner. For more information about different roles, see Teams and roles - RBAC.

Runner installation methods and steps

Traceable provides various methods for installing runners. Click the tabs according to your requirements to install a runner in your system.

From the Platform

As a Service

Using Helm Chart

On AWS ECS using CloudFormation

On AWS ECS using Terraform

To start configuring a runner on the Traceable platform, navigate to Testing → Settings → Runners, and click + Configure Runner. In the Configure new runner window, complete the following steps:

Specify the Runner Name, for example, SampleRunner.
Specify the Label(s) you wish to use to identify the runner, for example, default. You can use these labels to assign runners to scans during scan creation. For more information, see Understanding runner labels.
Click Generate New Token or specify an existing platform token for setting up the runner.

Traceable displays the commands you must execute in your terminal to set up the runner on your server. You can do this using either Docker or Linux. Upon successful execution, Traceable displays the runner on the Runners page.

By default, the binary command runs in the background. The Docker command displayed on the platform interactively runs in the foreground. To run the Docker command in the background, use the following command. Replace the runner's name with the name of your runner:

docker run --rm -d -v ~/.traceable_docker:/app/userdata traceableai/traceable-cli:latest runner start --traceable-server api.traceable.ai --runner-name newrunner --token ****

The following is an explanation of the Docker command:

docker run is the command to run a Docker container.
--rm removes the container automatically after it exits.
-d runs the container in detached mode.
-v ~/.traceable_docker:/app/userdata mounts the local directory ~/.traceable_docker to the /app/userdata directory inside the container. This allows the container to access and modify files in the local directory.
traceableai/traceable-cli:latest specifies the image to use for the container.
runner start runs the start command of the Traceable Runner program within the container.
--traceable-server api.traceable.ai specifies the URL of the Traceable Server to connect to.
--runner-name newrunner sets the name of the runner to “newrunner”.
--token **** sets the authorization token required to connect to the Traceable Server.

You can configure the runner as a systemd service. To do so, see the following sections:

Step 1 — Pre-installation

Before configuring Runner as a service, complete the following steps:

Generate a new API token in the Traceable platform. To do this:
1. Navigate to Testing → Suites and select any suite.
2. In the page’s top right corner, click Start Scan.
3. In the Start New Scan window, under Generate Token, click Generate New Token.
You can also use an existing API token.
This is required while installing Runner as a service.
Navigate to the terminal on your machine and enter the following command to download the installation script:
```
curl -O https://downloads.traceable.ai/cli/release/latest/install.sh
```
Note
The install.sh script is supported on a Linux machine.

Step 2 — Installation

Enter the following command to install Runner as a service:

bash install.sh --service --token <traceable-api-token> --server <traceable-server>

See the table below for the available options you can use in the above command:

Option	Description	Default Value
`--prefix <prefix-path>`	The installation prefix	`/home/ubuntu/.local`
`--version <version>`	The CLI version to install	`latest`
`--runner-name <runner-name>`	A custom name for the runner	`<hostname>-runner`
`--file <filepath>`	The path to the Traceable distribution zip file	Downloaded from Traceable’s download site
`--no-prompt`	Does not provide a prompt on confirmation	-
`--service`	Install the runner as a `systemd` service.	-
`--user <user>`	Install the runer as a user. Run as the `<user>` for the service	`ubuntu`
`--group <group>`	Install the runner as a group. Run as the `<group>` for the service.	`ubuntu`
`--server <traceable-server>`	The Traceable server to connect to.	`api.traceable.ai:443`
`--token <traceable-api-token>`	The Traceable user token for authentication.	-
`--traceable-home <path>`	The path to the Traceable home folder.	`/home/ubuntu`
`--logfile <logfile-path>`	The path to the file that should store the runner logs. By default, Traceable outputs to `stdout`.	-
`--logdir <logdir-path>`	The path to the directory that stores all the logs. By default, Traceable uses the `TRACEABLE-HOME` directory.	-
`--loglevel <log-level>`	The level of logs you want for the runner. This can contain the following values: INFO (default) DEBUG TRACE PROGRESS	-
`--scan-log-max-retention-count <num>`	The maximum number of files that Traceable should retain in the logs folder. When the files reach the limit, the oldest ones are replaced with new ones.	-
`--scan-log-max-retention-days <days>`	The maximum number of days for which Traceable should retain the log files.	-
`--max-log-file-size <size-in-bytes>`	The maximum size of a log file (in bytes).	-
`--tmp-dir <path-to-directory>`	The directory to use during installation and runtime.	System Temp Directory
`--help`	Show this table for reference in your terminal.	-

Step 3 — Post-Installation

Post-installation of the runner, you must complete the following steps to start the runner:

Enter the following command to restart the service:
```
sudo systemctl daemon-reload
```
Enter the following command to start the service:
```
sudo systemctl start traceable-runner
```

Enter the following command to check the status of the service:

sudo systemctl status traceable-runner

The output of the above command should look like this:

● traceable-runner.service - Traceable CLI
     Loaded: loaded (/etc/systemd/system/traceable-runner.service; disabled; vendor preset: enabled)
     Active: active (running) since Mon 2025-01-06 07:07:19 UTC; 9s ago
   Main PID: 283083 (traceable)
      Tasks: 15 (limit: 1069)
     Memory: 405.3M
        CPU: 1.850s
     CGroup: /system.slice/traceable-runner.service
             ├─283083 /home/ubuntu/.local/traceable/bin/traceable runner start --runner-name traceable-runner
             ├─283085 /tmp/staticx-EJFPfK/traceable_shared runner start --runner-name traceable-runner
             └─283086 /tmp/staticx-EJFPfK/traceable_shared runner start --runner-name traceable-runner
Jan 06 07:07:19 loyal-tick systemd[1]: Started Traceable CLI.
Jan 06 07:07:21 loyal-tick traceable[283086]: Traceable CLI 1.10.19 (linux)
Jan 06 07:07:21 loyal-tick traceable[283086]: [2025-01-06 07:07:21,625]:INFO: Refreshing config
Jan 06 07:07:21 loyal-tick traceable[283086]: [2025-01-06 07:07:21,626]:INFO: Connecting to `api.traceable.ai` with token `YTU2**********...`
Jan 06 07:07:23 loyal-tick traceable[283086]: [2025-01-06 07:07:23,999]:INFO: Setting log level to: INFO
Jan 06 07:07:24 loyal-tick traceable[283086]: [2025-01-06 07:07:24,000]:INFO: Acquired lock on /home/ubuntu/.traceable/runner.pid
Jan 06 07:07:24 loyal-tick traceable[283086]: [2025-01-06 07:07:24,001]:INFO: Finding hook files in /home/ubuntu/.traceable/hooks
Jan 06 07:07:24 loyal-tick traceable[283086]: [2025-01-06 07:07:24,015]:INFO: Started runner name: loyal-tick-runner (id: e1f123b7-3815-5e94-b8bd-8eb1234c7814). Listening for scan jobs...

In the above output, the dot (●) shows the status of a runner. The table below describes the dot colors and their corresponding status descriptions:

Color	Status Description
Green	The runner is being activated or is currently active.
Red	The runner has failed.
White	The runner is currently inactive.

Enter the following command to enable the service to start on system boot:
```
sudo systemctl enable traceable-runner
```

You can run more than one runner on the same machine for both option 1 and option 2. For more information on how to run more than one runner on a single machine, contact Traceable support at support@traceable.ai.

Complete the following steps to install the runner using the Helm chart:

Enter the following command to add the repo:

helm repo add traceableai https://helm.traceable.ai

Enter the following command to update the repo:
```
helm repo update
```

Create values.yml file

Create a values.yml file based on the sample provided below. Make sure to add the correct values for traceableToken and traceableServer in the file.

replicaCount: 1
resources:
  limits:
    cpu: 2.0
    memory: 4Gi
  requests:
    cpu: 2.0
    memory: 4Gi
astRunnerArgs:
  name: traceable-runner-helm   # Name of the runner
  traceableServer: api.traceable.ai   # Traceable Server
  traceableToken: ""   # Replace this with actual token value
  maxRetries: 1   # Number of Request Retries
  idleTimeout: 10   # Idle Timeout before aborting a scan
  requestDelay: 0   # Request delay delay between requests
  threads: 20   # Number of threads to run on
  logfile: stdout   # Log file name
  loglevel: INFO   # Set log level
externalTraceableTokenSecret:
  name: "" # Name of the secret
  key: "" # Key of the secret

Note
Make sure that the externalTraceableTokenSecret.key that you provide is valid.
If you specify the token as plain text under astRunnerArgs.traceableToken and as secret under externalTraceableTokenSecret.key, Traceable ignores the plain text and uses the secret key.

Enter the following command:

helm install <release_name>  traceableai/traceable-runner -f values.yaml

You can configure runners on AWS ECS (Elastic Container Service) using CloudFormation. Download the template file by contacting Traceable support, and install the runner in your AWS console. For the steps to do this, see Installation using CloudFormation.

You can configure runners on AWS ECS (Elastic Container Service) using Terraform. Download the Terraform file by contacting Traceable support, and install the runner in your shell. For the steps to do this, see Installation using Terraform.

Understanding Runner labels

Runner labels are categories that enable you to define and control which runners are eligible to execute scans or tasks. You can assign one or more labels to a runner to describe its purpose or any other detail. For example, labels such as production, sandbox, or us-east can indicate the runner’s deployment region or context.

Runner selection based on labels

You can define one or more labels while configuring runners. For more information, see Installing a Runner.

Further, you can select one or more runner labels while creating a scan. For more information, see Creating a Scan.

Runner Label Selection during Scan Creation

Traceable selects runners based on label matching, where any runner sharing at least one label with the ones selected during scan creation is eligible. If multiple runners match, Traceable may choose either of them to execute the scan.

The following illustration highlights runner selection based on the label assigned to it.