qTest Automation Host 2.x Manually Upgrade Guide on Linux

[Updated] For Elite users: starting from version 2.0.3, it is highly recommended to upgrade the automation host from qTest Launch following these instructions.


This article provides an EXAMPLE to upgrade automation host version 1.3.8 to 2.x on Linux. If your automation host version is greater than 1.3.8, you can still follow this article to manually upgrade it to a newer version.

IMPORTANT: We highly recommend that Elite Users using an Automation Host version 2.0.3 and beyond upgrade their Automation Host from within qTest Launch using these instructions.

Download qTest Automation Host 2.x

Follow these steps to Downlaod the qTest Automation Host version 2.x:

  1. Refer to the Download Automation Host article and download the qTest Automation Host 2.x for Linux. It is highly recommended that you download the latest 2.x version to benefit from bug fixes and enhancement.
  2. Open the Terminal
  3. Change to directory where you are going to install automation host 2.x, e.g. /usr/local/qtest-automation-host. Use this command:
    $ cd /usr/local/qtest-automation-host
  4. Extract the bundle:
    $ tar -zxf agentctl-[version]-linux-x64-full.tgz


  • You can extract the package to wherever you'd like, just need to make sure the directory exists.
  • Replace [version] in the command to the actual version that you have chosen to download, e.g. 2.0.1

Get your qTest API token

  1. Login to qTest Manager as an Administrator and access the Resources page.
  2. Expand the APIs and SDK section.
  3. Copy the API Token, as shown below:


Upgrade to qTest Automation Host 2.x

Follow these steps to Upgrade the qTest Automation Host 2.x:

  1. If your current Automation Host 1.3.8 is running in Terminal, press Ctrl + C to stop it
  2. If you have installed qTest Automation Host 1.3.8 as a service, follow below steps to remove it. Otherwise, move to step #3.
  3. Open the Terminal and execute following commands at agentctl-1.3.8 directory to uninstall agentctl-1.3.8 as service:
    $ cd /path/to/agentctl-1.3.8
    /path/to/agentctl-1.3.8$ sudo ./uninstall/path/to/agentctl-1.3.8$ sudo systemctl status qtest-automation-agent
  4. Configure the Automation Host 2.x
  5. Open Terminal and navigate to the extracted Automation Host 2.x folder using the following command:
    $ cd /usr/local/qtest-automation-host/agentctl-[version]
  6. Execute this command to configure Automation Host 2.x:
    /usr/local/qtest-automation-host/agentctl-[version]$ ./agentctl  config -Phost=[ip_address] -Pport=[agent_port] -Pqtest.url=[qtest_url] -Pqtest.token=[qtest_token]
    Note: -Phost and -Pport parameters are optional
    • If you do not specify -Phost parameter, localhost will be used
    • If do you not specify -Pport parameter, 6789 will be used
      • For example:
        /usr/local/qtest-automation-host/agentctl-[version]$ ./agentctl config -Pqtest.url= -Pqtest.token=[qtest_token]

        For more detail about how to configure qTest Automation 2.x, follow this article: Install and Configure the Automation Host
  7. Run the backup command to backup data and configurations of the Automation Host 1.3.8:
    /path/to/agentctl-1.3.8$ ./agentctl backup -Plocation="/path/to/agentctl-1.3.8/build/qautomation"
    • For example:
      /usr/local/qtest-automation-host/agentctl-1.3.8$ ./agentctl backup -Plocation="/usr/local/qtest-automation-host/agentctl-1.3.8/build/qautomation"

      If the example command was successful, a backup file will be created at /usr/local/qtest-automation-host/agentctl-1.3.8/backup/
  8. Next, navigate to the Automation Host 2.x directory. Execute the below command to copy data and configurations of automation host 1.3.8 to Automation Host 2.x:
    /path/to/agentctl-[version]$ ./agentctl restore -Pbackup-file="/path/to/backup file]"
    • For example:
      /usr/local/qtest-automation-host/agentctl-[versiom]$ ./agentctl restore -Pbackup-file="/usr/local/qtest-automation-host/agentctl-1.3.8/backup/"

Start qTest Automation Host 2.x

Start the agent from the Terminal using the following command:

/usr/local/qtest-automation-host/agentctl-[version]$ ./agentctl start

Note: if you want the Automation Host to start automatically whenever the system starts, you need to install it as a service by following this article: Install Automation Host as a Service.

Powered by Zendesk