Skip to Content

Install a Windows private agent


These are the instructions on downloading and installing the Harmony private agent on Windows. Prior to installation, we recommend reviewing Agent groups high availability and load balancing and Private agents best practices tech talk.

For information on system requirements, see System requirements for Windows private agents.

An alternative to using the standard Windows private agent installer is to configure and run a silent and unattended installation of a private agent. For more information, see Install a Windows quiet agent.


Known Issue: When installing a private agent 10.69 or later (for 10.x agents) or 11.8 or later (for 11.x agents) on Windows 2019 or Windows 10, a warning message may appear that reads "Windows protected your PC" with a note that Microsoft Defender SmartScreen prevented an unrecognized app from starting. To proceed with the agent installation, click More info within the warning message dialog and then click Run anyway.

Download a Windows private agent

These instructions on downloading a Windows private agent assume you have already created an agent group and private agent(s) for your organization within the Management Console Agent groups and Agents pages, respectively.

  1. Log in to the Harmony portal and go to Management Console > Agents > Agent Groups.

  2. In the upper portion of the screen, select the agent group row. The lower half of the screen should now list the Available Agents within the selected agent group.

  3. In the lower portion of the screen, select the agent row. Then click the Action dropdown on the far right and select Download for Windows EXE.

  4. The Windows agent executable can be downloaded, stored locally, and reused as needed for any additional private agents as they are added.

Install a private agent

Installing more than one agent in an agent group automatically allows for high availability. Installing multiple agents in an agent group also automatically allows for load balancing. See Agent groups high availability and load balancing for additional information. Before installing, check that all software requirements and notices have been met.

On each agent within the agent group:

  1. Run the downloaded Windows agent executable file, and follow the prompts.

  2. At the Login Credentials prompt, enter your Harmony credentials (the email address and password you use to log in to


    If your organization and account use single sign-on (SSO), your normal SSO credentials will not work. You must use Harmony credentials to install private agent(s).

  3. Follow the prompts to select your organization, agent, etc. The available options are those you have already configured from the Management Console.


    You must be a member of a role that has either Admin or Agent-Install permissions.

  4. At the Select Install Mode prompt, choose the mode depending on whether you want to install the PostgreSQL instance that is bundled with the agent or have an existing installation of PostgreSQL that you would like to use:

    • Quick Install (Recommended): Installs all components needed to run a private agent including a PostgreSQL agent database and driver. Use this option if you have never installed PostgreSQL or a private agent on this computer before, or if you have properly uninstalled all components following the instructions in Uninstall a private agent. More information about the PostgreSQL database that is bundled with the agent is provided in PostgreSQL requirements in System requirements for private agents.


      When you are prompted to set up your PostgreSQL password, note that the password must conform to your system's password policies regarding length and complexity.

    • Advanced: Installs a private agent and configures a private agent database to use an existing PostgreSQL installation. You will need to provide your PostgreSQL credentials. You may wish to use this option if you want to manage passwords separately within each application.

      The existing PostgreSQL database version must match that expected by the agent version:

      • For 11.0 Windows private agents and later, an existing PostgreSQL database that is version 14.5-1 has been confirmed to work. Other 14.x PostgreSQL versions are expected to work but have not been tested.
      • For 10.x Windows private agents, the existing PostgreSQL database must be version 9.6.x.

      An existing 14.x PostgreSQL database must be set to use MD5 password encryption:

      postgres=# set password_encryption TO 'md5';

  5. After installation, the agent will attempt to start and establish a connection with Harmony. This process can take more than a minute to complete.


    Harmony private agents installed on Microsoft Azure servers require a reduced agent heartbeat interval.

    You can check the status of the agent in the Management Console Agents page. Once an agent starts, its status should be Running.


    In agent versions 10.61, 10.62, 10.63, and 11.1, the status will be Stopped until an agent's agent group is associated with an environment.