Upgrading a Runner

New
  • Updated on Jan 2, 2026
  • Published on Dec 30, 2025
  • 2 minute(s) read
Prev Next

Upgrading a runner depends on how the runner was originally deployed. The following tabs highlight the steps to ensure that runners are successfully upgraded.

Note

You can check the currently installed runner version by running the traceable version command before initiating an upgrade.

Traceable provides you with the option to install the runner from the Platform using Docker. To upgrade the runner installed using Docker, you must pull the latest image and recreate the container. To do this, complete the following steps:

  1. Stop and remove the current runner:

    docker stop <runner_name>
docker rm <runner_name>
# Replace the <runner_name> placeholder with the actual runner name.

  2. Retrieve the latest runner image:

    docker pull traceableai/traceable-cli:v2

  3. Start the runner again:

    docker run --rm -d -v ~/.traceable_docker:/app/userdata traceableai/traceable-cli:v2 runner start --traceable-server api.traceable.ai --runner-name <runner_name> --token <traceable_api_token>
# Replace the <runner_name> and <traceable_api_token> placeholders with the actual values.

Complete the following steps to upgrade your runner:

  1. Stop the service:

    sudo systemctl stop traceable-runner.service

  2. Download and run the install command. This retrieves the latest binary and updates the service definition:

    curl -O https://downloads.traceable.ai/cli/release/v2/install.sh
bash install.sh --service --token <traceable-api-token> --server api.traceable.ai
# Replace the <traceable-api-token> with the actual value

  3. Reload the runner and restart it:

    sudo systemctl daemon-reload
sudo systemctl start traceable-runner

If any errors occur during the above steps, you can uninstall the runner and reinstall it. To do this, complete the following steps:

  1. Stop and disable the runner:

    sudo systemctl stop traceable-runner.service
sudo systemctl disable traceable-runner.service

  2. Remove the service files:

    sudo rm /etc/systemd/system/traceable-runner.service
# OR depending on your location
sudo rm /usr/lib/systemd/system/traceable-runner.service

  3. Re-install the runner:

    curl -O https://downloads.traceable.ai/cli/release/v2/install.sh
bash install.sh --service --token <traceable-api-token> --server api.traceable.ai
# Replace the <traceable-api-token> with the actual value

  4. Reload the runner and restart it:

    sudo systemctl daemon-reload
sudo systemctl start traceable-runner

For upgrading runners installed using the Helm chart, you must update the repository and run the upgrade command. To do this, complete the following steps:

  1. Update the Helm repository:

    helm repo update

  2. Upgrade the runner:

    helm upgrade <release_name> traceableai/traceable-runner -f values.yaml
# If you used a values.yaml file, you must include it in the above command
# Replace the <release_name> placeholder with the actual value used during installation

To upgrade your runner, you must update your CloudFormation template or Terraform configuration to reference the new Runner image version or tag, then apply the changes. This usually triggers a rolling update. However, if errors occur while upgrading your runner, you can complete the following steps:

  1. Delete the service — Navigate to your AWS console → ECS → Cluster, and delete the runner service. For more information, see Uninstalling a Runner, Installed on AWS ECS tab.

  2. Create a new service — Install the runner again using either CloudFormation or Terraform, according to your requirements.