---
title: "Upgrading a Runner"
slug: "upgrading-runner"
description: "Learn how to upgrade a Traceable Runner across Docker, Systemd, Helm, and AWS ECS deployments, including steps for pulling new images, updating configurations, and performing rolling updates."
updated: 2026-01-02T05:59:31Z
published: 2026-01-02T05:59:31Z
---

> ## 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.

# Upgrading a Runner

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]
> Note
> 
> You can check the currently installed runner version by running the `traceable version` command before initiating an upgrade.

Platform (Docker)As a systemd service (Linux)Helm chart (Kubernetes)AWS ECS (CloudFormation and Terraform)

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:

```bash
docker stop <runner_name>
docker rm <runner_name>
# Replace the <runner_name> placeholder with the actual runner name.
```
2. Retrieve the latest runner image:

```bash
docker pull traceableai/traceable-cli:v2
```
3. Start the runner again:

```bash
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:

```bash
sudo systemctl stop traceable-runner.service
```
2. Download and run the `install` command. This retrieves the latest binary and updates the service definition:

```bash
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:

```bash
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:

```bash
sudo systemctl stop traceable-runner.service
sudo systemctl disable traceable-runner.service
```
2. Remove the service files:

```bash
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:

```bash
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:

```bash
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:

```bash
helm repo update
```
2. Upgrade the runner:

```bash
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](/v1/docs/uninstalling-a-runner), **Installed on AWS ECS** tab.
2. **Create a new service** — Install the runner again using either [CloudFormation](/v1/docs/install-tpa-using-cloudformation) or [Terraform](/v1/docs/runners-using-terraform), according to your requirements.