qTest Automation Host 2.x Installation Guide on Windows


In this article, we will walk you through how to install qTest Automation Host version 2.x on a Windows machine.

Note: This article walks through installing the Automation Host on a Windows machine using the recommended Web Interface. There is an advanced installation method that requires you using the command line, e.g. when IT admin want to mass install automation host to multiple machines in the network, refer to this article to learn more about this method.

Download qTest Automation Host 2.x for Windows

  1. From the Download Automation Host page, download the qTest Automation Host 2.x for Windows.
    IMPORTANT: It is highly recommended that you download the latest 2.x version to benefit from bug fixes and enhancements.
  2. Extract the agentctl-[version] to a desired installation folder, e.g. C:\qtest-automation-host\agentctl-[version]. Make sure you read important notes below before you perform this step:
    • It is NOT recommended to extract and install automation host in the root of C: drive, e.g. C:\agentctl-[version], since it will cause the Auto Upgrade functionality failed. The reason for the failure is the auto upgrade process will not be able to create a new folder for the new version at the root of C: drive due to Windows restriction. You are highly recommended to extract automation host package under at least one sub level folder, e.g. C:\qtest-automation-host\agentctl-[version]
      • One of our customers also experienced an issue with auto start up functionality in Automation Host 2.2.2 where it did not start the Automation Host when Windows starts up. It is due to the Automation Host was installed under C:\agentctl-2.2.2 and for some security reasons the start up script failed to execute. Although this is not universal issue as we could NOT reproduce it in our test environment, you are still advised to NOT install Automation Host under root of C: drive to avoid this unexpected issue
    • It is highly recommended to download and install 7-zip tool and use it to extract the package as to avoid issues with the long file path. For more detail, read this article.
      • Starting from Automation Host 2.2.2, we fixed the issue with the long file path so the use of 7-zip is optional
    • Replace [version] to the actual version that you have chosen to download, e.g. 2.1.1
    • If you plan to install multiple automation host instances on Windows, it is important that you create a parent folder for each instance to easily identify it, as well as to avoid issues when upgrading each instance (see the notes above). The best practice is to suffix the parent folder with a number, then extract the package to that parent folder.
      For EXAMPLE:
      • Instance #1: C:\qtest-automation-host-1\agentctl-[version]
      • Instance #2: C:\qtest-automation-host-2\agentctl-[version]
      • ...
      • Instance #N: C:\qtest-automation-host-N\agentctl-[version]

Download the Automation Host Video

Note: For the highest quality, view the video in full-screen mode.

Acquire your qTest API Token

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



The token will be automatically changed by qTest Manager if below events occur:

  • Users change their password in qTest Manager OR
  • Users switch authentication type, e.g. from authenticating with qTest using Username and Password to SSO or LDAP, and vice versa

Install and Configure Automation Host via Web Interface

From Command Prompt, execute the following command: 

\path\to\agentctl-[version]> agentctl.bat start

Wait for a couple of minutes for the Automation Host to fully start. Open your web browser and navigate to http://localhost:6789. You'll see the registration UI being shown like below.


Next, enter information to register the automation host:

  • Host Name: Enter a meaningful name for the host
  • qTest URL: Your qTest Site URL
  • qTest Token: Enter the token from the step Aquire your qTest API token
  • Full Name: Your full name
  • Configure Proxy: If you are connecting to the internet through your corporate proxy, select Enable checkbox to enable proxy configuration
    • Script: If your proxy server is configured with a script, enter the URL to access your PAC (Proxy Auto-Configuration) file
    • Host: Enter the proxy host address. This can be either the IP address, computer name, or dns name of this proxy server.
      • Note: If you specify both Script and Host, the automation host will connect to the script-based proxy server first, then connect to the proxy host if the connection to the script-based one failed.
    • Port: Specify the port that the proxy server is running on. This parameter is required.
    • Username: If your proxy server requires basic authentication, enter a username to authenticate with the proxy. Otherwise, leave this field empty.
    • Password: If your proxy server requires basic authentication, enter a password to authenticate with the proxy. Otherwise, leave this field empty.
  • Run on Start Up: Available on Automation Host 2.2.2 and later. Select this option to automatically start the Automation Host when the machine starts



Select Register to register the Automation Host with qTest Manager. This process will take a while, once it's finished you'll be automatically navigated to the home page.

Access the Automation Host

Open your browser and enter the URL: http://<host>:<port>

  • host: the IP address or computer name that you specified when configuring the host via config command (available in Automation Host 2.1.1 and later) or start command
  • port: the port that you specified when configuring the host via config command. If you did not specify the port, use the default 6789


Install qTest Automation Host as a Service on Windows

If you want the Automation Host to automatically start when system starts, there are two options:

  1. Install Automation Host as a Windows Service OR
  2. Configure it to run at system start up (highly recommended from Automation Host 2.2.2). Refer to the previous instructions to learn how to configure Automation Host to automatically start when system starts

IMPORTANT: Limitation of Automation Host Service on Windows

When Automation Host is installed and running as a Windows service, it cannot launch your application that has a Graphic User Interface (GUI). It also cannot execute your tests that interact with a UI application. From our experience, TestComplete, UFT, Tosca UI testing, Selenium-based tests that launch a web browser, etc. are applications that cannot be launched from Automation Host running as a Windows service.

Although the limitation can be overcome, building a Windows service to launch a GUI application is considered a security vulnerability: We decided not to follow this path.

If the application that you are going to integrate with Automation Host has no GUI, or not going to interact with a GUI application, you are good to proceed to these instructions. Otherwise, we recommend you run automation host on Windows Command Prompt or configure it to run on system start up (only available from Automation Host 2.2.2 or newer) and let it launches your application from there.

Install qTest Automation Host as a single service on Windows

Notes: if you are using Automation Host 2.1.1 or later AND you want to install multiple instances of Automation Host as services on Windows, skip to next section.

1. Run the command prompt as an Administrator, and access the agentctl directory.

2. If the agent is running in the Console, stop it with this command:

\path\to\agenctl-[version]> agentctl.bat stop

3. Execute the following command to install qTest Automation Host as a service on Windows.
Note: <service name> is optional. If you do not specify service name, "qtest-automation-agent" will be used as the service name.

\path\to\agenctl-[version]> install.bat "<service name>"

Install Multiple qTest Automation Host Instances as Services on Windows

Notes: This feature is only available for the Automation Host version 2.1.1 and later.

Follow these steps if you want to install multiple automation host instances as services on Windows:

  1. Extract the downloaded Automation Host package to multiple folders. Make sure you create a parent folder for each automation host instance to easily identity it as well to avoid an issue when upgrading that instance. EXAMPLE below shows how we extract each package inside a parent folder whose name is suffixed with a number:
    • Instance #1: C:\qtest-automation-host-1\agentctl-[version]
    • Instance #2: C:\qtest-automation-host-2\agentctl-[version]
    • ...
    • Instance #N: C:\qtest-automation-host-N\agentctl-[version]
  2. Open the Windows Command Prompt as Administrator. Access each automation host folder, then perform steps 3-5 for each folder
  3. Install and Register the Automation HostIMPORTANT: make sure you give each instance a unique Port number via -Pport parameter. It is also highly recommended to give each instance a unique automation host name via -Phostname parameter in config or start command
  4. Stop the automation host instance if it is running in the Windows Command Prompt: agentctl.bat stop
  5. Execute the command below to install the host as a service.
    IMPORTANT: you must give the service a unique name via <service name> parameter:
    \path\to\agenctl-[version]> install.bat "<service name>"

Uninstall qTest Automation Host Service

If you want to uninstall qTest Automation Host service, open the command prompt as an Administrator. Access the agentctl-[version] directory. Execute the following command:

\path\to\agenctl-[version]> uninstall.bat

If you installed multiple instances of automation host as services on Windows, access to each automation host folder and execute the above uninstall.bat command.

Powered by Zendesk