qTest Automation Host 2.x Manually Upgrade Guide on Mac OS

[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 Mac OS. 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.

Download qTest Automation Host 2.x

1. Go to this page Download Automation Host and download the qTest Automation Host 2.x for Mac. It is highly recommended that you download the latest 2.x version to benefit from bug fixes and enhancement.

2. Open Terminal

3. Move the downloaded file to /usr/local/qtest-automation-host directory:

$ sudo mv agentctl-[version]-osx-x64-full.tgz /usr/local/qtest-automation-host

4. Change current directory to /usr/local/qtest-automation-host:

$ cd /usr/local/qest-automation-host

5. Extract the bundle:

/usr/local/qtst-automation-host$ tar -zxf agentctl-<version>-osx-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 to Resource page

2. Expand APIs and SDK section

3. Copy the API Token, as show from below screenshot.


Upgrade Automation Host to 2.x

1. If your current Automation Host 1.3.8 is running in Terminal, press Ctrl + C to stop it

2. Open Terminal and navigate to extracted Automation Host 2.x folder

$ cd /usr/local/qtest-automation-host/agentctl-<version>

3. Execute below command to configure the agent 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


/usr/local/qtest-automation-host/agentctl-<version>$ ./agentctl config -Pqtest.url= -Pqtest.token=[qtest_token]

For more detail about how to configure qTest Automation Host 2.x, follow this article: Install and Configure the Automation Host

4. Run the backup command to copy 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"


/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 command was successful, a backup file will be created at /usr/local/qtest-automation-host/agentctl-1.3.8/backup/

5. Next, navigate to the automation host 2.x directory. Execute below command to copy data and configurations of automation host 1.3.8 to automation host 2.x

/usr/local/qtest-automation-host/agentctl-<version>$ ./agentctl restore -Pbackup-file="/path/to/agentctl-1.3.8/backup/"


/usr/local/qtest-automation-host/agentctl-<version>$ ./agentctl restore -Pbackup-file="/usr/local/qtest-automation-host/agentctl-1.3.8/backup/"

Start qTest Automation Host 2.x

Start the agent from Terminal:

/usr/local/qtest-automation-host/agentctl-<version>$ ./agentctl start

Note: if you want the automation host to be started automatically when the system starts, you need to install it as a service by following this article: Install Automation Host as a Service

Powered by Zendesk