--- title: "Installing a Runner" slug: "installing-a-runner" description: "Learn how to install Traceable runners using the platform, CLI, Helm, or AWS ECS. Follow step-by-step guidance to configure runners, apply labels, and enable reliable security scan execution." updated: 2026-05-21T12:21:54Z published: 2026-05-21T12:21:54Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Installing a Runner ##### Updates (April 2026 to June 2026) - *May 2026* — - Updated the page to include the `config` and `hook` configuration options when installing a runner using a Helm chart. For more information, see [Runner installation methods and steps](/v1/docs/installing-a-runner#runner-installation-methods-and-steps), **Helm Chart (Kubernetes)** tab. 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 fulfil the necessary software and hardware requirements for the runner to perform efficiently. For more information, see [Software and Hardware Requirements](/v1/docs/software-and-hardware-requirements). - Ensure that the machine on which 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 the 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 that you have generated the Platform API Token when setting up the runner *As a Service* or *Using a Helm Chart*. For the steps to generate the token, see [Public APIs](/v1/docs/public-apis). - 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](/docs/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. Platform (Docker)As a systemd service (Linux)Helm Chart (Kubernetes)AWS ECS (CloudFormation)AWS ECS (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: ![Configuring Runners](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_ast_runners_configuration.png) Configuring Runners 1. Specify the **Runner Name**, for example, *SampleRunner*. 2. 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](/docs/runners#understanding-runner-labels). 3. Click **Generate New Token** or specify an existing platform token to set 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 the runner you configured in Step 1 above: ```bash docker run --rm -d -v ~/.traceable_docker:/app/userdata traceableai/traceable-cli:v2 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 steps: #### Step 1 — Pre-installation Before configuring Runner as a service, complete the following step: 1. Navigate to the terminal on your machine and enter the following command to download the installation script: ```bash curl -O https://downloads.traceable.ai/cli/release/v2/install.sh ``` > [!NOTE] > 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 bash install.sh --service --token --server # Replace the and placeholders with the actual values ``` 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](https://downloads.traceable.ai) | | `--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: 1. Enter the following command to restart the service: ```bash sudo systemctl daemon-reload ``` 2. Enter the following command to start the service: ```bash sudo systemctl start traceable-runner ``` 3. Enter the following command to check the status of the service: ```bash sudo systemctl status traceable-runner ``` The output of the above command should look like this: ```bash ● 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. | 4. (Optional) Enter the following command to enable the service to start on system boot: ```bash sudo systemctl enable traceable-runner ``` You can run more than one runner on the same machine if you installed it using the platform or as a service. For more information on how to run more than one runner on a single machine, contact Traceable support at [support@traceable.ai](mailto:support@traceable.ai). Complete the following steps to install the runner using the Helm chart: 1. Enter the following command to add the repo: ```bash helm repo add traceableai https://helm.traceable.ai ``` 2. Enter the following command to update the repo: ```bash helm repo update ``` 3. Create a `values.yml` file based on the sample provided below: ```yaml 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 the Platform 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 # User configuration file (config.yaml) # When enabled, this will mount a ConfigMap containing the user configuration at /app/userdata/config.yaml # Example: # config: #  content: | #    scan: #      plugins: #        pre_hooks: #          - xsrf_posthook: #              disabled: true #        post_hooks: #          - xsrf_posthook config:  enabled: false  content: |    # Add your configuration here # User hook scripts # These scripts will be mounted under /app/userdata/hooks/ # Example: # hooks: #   - name: foo.py #     content: | #       print("Hello world") hooks: [] ``` > [!NOTE] > 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. 4. Enter the following command to install the runner: ```bash helm install  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 instructions on how to do this, see [Installation using CloudFormation](/docs/runners-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](/docs/runners-using-terraform). --- ## Understanding runner labels Runner labels help you organize runners and control which ones are eligible to execute specific scans or tasks. By assigning one or more labels to a runner, you can describe its purpose, environment, or deployment context. For example, labels such as `production`, `sandbox`, or `us-east` can indicate where a runner is deployed or the type of workloads it should handle. This allows you to route scans to appropriate runners without manually selecting individual instances. When configuring a runner, you assign labels during the setup process. Later, while creating a scan, you select one or more labels to define which runners are eligible to execute that scan. Traceable then matches the selected labels against available runners. ![Runner Label Selection during Scan Creation](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_runner_label_scan_creation.png) Runner Label selection during scan creation A runner becomes eligible if it shares at least one label with the labels selected during scan creation. If multiple runners match, Traceable automatically selects one of them to execute the scan based on availability. The following illustration highlights runner selection based on the label assigned to it. ![Runner Selection](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_ast_runner_labels_selection.png) Runner Selection Using runner labels ensures better workload isolation, simplifies runner management, and enables flexible scan execution across different environments and deployment setups. Dynamic Application Security Testing (DAST): DAST involves testing an application while it is running to identify vulnerabilities that may not be apparent from analyzing the source code. DAST can help to identify vulnerabilities in the application's runtime environment, such as configuration issues or network vulnerabilities. ## Related - [Runners and CLI](/runners.md) - [Understanding Runners Dashboard](/understanding-runner-dashboard.md) - [Uninstalling a Runner](/uninstalling-a-runner.md) - [Software and Hardware Requirements](/software-and-hardware-requirements.md)