Use the Update Agent Software feature to update the Horizon Agent Installer for Dedicated Desktop - Traditional Clone assignments.

Note: You can also update agent software for a Dedicated Desktop - Instant Clone assignment by updating the image and pushing changes to the assignment. This process is described in Update Agent Software for an Image.

At a high level, the system's agent update capability works as follows:

  • The system makes regular contact with the VMware CDS software distribution network to see if a new version of the Horizon Agents Installer is available. It downloads the new version to a file share that you have set up on a local machine. The update file is then automatically imported into the system and made available to assignments.
  • After a new version is downloaded, the Assignments page reflects that an update is available. A visual indicator is displayed for those dedicated VDI desktop assignments that have the agent-related software at a level prior to the new version.
    Screenshot where the Assignments page shows a blue dot on the dedicated VDI desktop assignment, indicating an agent update is available.

  • You select the dedicated VDI assignment and start the agent update wizard. Besides selecting the agent version, in the agent update wizard, you can optionally specify the following items.
    Option Description
    Available VMs to Users Use this field to specify a percentage of the assignment's VMs to keep available for users during the update.

    By default, the system marks all of the desktops for maintenance as the update starts. You can use this field to ensure a higher percentage of a small-sized pool is available as the system goes through and updates the desktops. Setting a higher availability percentage results in an adjustment to the number of desktops currently marked for maintenance.

    Skip VMs with Logged-In User Have the system skip updating VMs that have a logged-in user, a session that is either active or disconnected. This setting avoids the system's default behavior of forcing end users off their desktop when the update process starts on that desktop.
    Retry Skipped VMs and Job Timeout When you have the system skip updating VMs that have a logged-in user, you can optionally specify whether to have the system automatically retry updating any skipped VMs. In this case, after the system has gone through the assignment's desktop VMs and updated those VMs without logged-in users, the system:
    1. Checks the ones that it initially skipped to see if those VMs have logged-in users.
    2. Updates any of the skipped VMs which have no logged-in users.
    3. Periodically repeats steps 1 and 2 until the time specified in the Job Timeout field has elapsed.

    If you do not have the system automatically retry the skipped VMs, you can manually take care of those VMs later.

    Important: VMs that encounter an error during the update process are not retried. For a failed update, the VM rolls back to the agent version that it had before the update process started.
  • After you submit the update task in the wizard's last step, the system begins updating the desktops in the assignment. When updating the assignment, the system updates a batch of VMs in parallel. By default, the system uses 30 VMs for each batch until the remaining number of VMs to update is less than 30. At that point, that final set is for updating those remaining VMs. It takes approximately 30 minutes to fully update a VM. The batch size cannot be larger than 30. If the assignment has 30 or fewer desktops, all desktops in the assignment are updated together. Your VMware representative can adjust the batch size if you request it.

    The number of in-progress VMs depends on whether you specified to have a percentage of the VMs to be kept available during the update. When you set an availability percentage, the system adjusts the set of in-progress VMs to meet the availability percentage.

  • At the end of the agent update process, the assignment's summary page lists the version of the Horizon Agents Installer that is in effect.

During the time the system is updating the desktops, the desktops' end users encounter the following behaviors:

  • If a desktop has an active session and you kept No for Skip VMs with Logged-In User, that user is warned five minutes before the update occurs. This five-minute warning is to give the user time to save any in-progress work.
  • If a user attempts to log in to a desktop that is being updated, the login is unsuccessful and the user receives a message that the desktop is not yet available.

Upon request, your VMware representative can make the following adjustments in your environment:

  • Adjust the interval between scans for new Horizon Agents Installer versions.
  • Adjust the wait time for scans after tenant startup.
  • Adjust the default batch size from 30.
  • Set your system to restart VMs before installing agents.


  • You must have created an Agents file share and added it to your environment. This means that you select Agents for the file share type when you create the file share. Agents file shares are used only for importing Horizon Agents Installer files. See Managing File Shares.
  • The image must already have the following agents installed:
    • One of the following:
      • DaaS Agent or later
      • DaaS Agent 8.0.0-8159435 or later
    • Horizon Agent or later


  1. Click Assign.

    The Assignments page displays, with a blue dot appearing next to the name of any assignment that has an Horizon Agents Installer update available. If you hover over a blue dot, a popup displays indicating the new version of the Horizon Agent Installer available for that assignment.

  2. Select the check boxes for one or more assignments. By selecting multiple assignments, you can update all of them to a common Horizon Agents Installer versions.
  3. Click Update Agent Software.
    The Agent Update dialog displays.
    Screenshot of the Agent Update wizard for updating agents on a dedicated VDI desktop assignment.

  4. In the Software step, select the update version you want to use from the drop-down list.
  5. (Required) In the Available VMs to Users field, specify the percentage of desktop VMs in the assignment that you want powered on and available to end users during the upgrade process.
    Note: If you do not need desktops available, type a zero (0). You must specify a value for Available VMs to Users, even when you do not care about having desktop VMs available to users during the update process.
  6. (Optional) To have the system skip those desktops that have logged-in users, set the Skip VMs with Logged-In User toggle to Yes.
    When that toggle is set to Yes, the Retry Skipped VMs toggle appears.
    Screenshot shows the Skip VMs with Logged-In User toggle.

  7. (Optional) To have the system automatically retry any of skipped VMs, set the Retry Skipped VMs toggle to Yes.
    When the Retry Skipped VMs toggle is set to Yes, the Job Timeout field appears.
    Screenshot shows the Job Timeout field that appears when the Retry Skipped VMs toggle is set to Yes.

  8. (Optional) In the Job Timeout field, specify the time period over which you want the system to continue automatically trying to update the skipped VMs.
    The Job Timeout field sets the number of minutes that the system retries updating the skipped VMs. Every 30 minutes, the system tries to update the skipped VMs until it reaches the end of this time period or until all of the assignment's desktop VMs have been updated.

    You can enter a value that ranges from 240 minutes (4 hours) to 1440 minutes (24 hours). The default value is 720 minutes (12 hours).

    Note: VMs that encounter an error during the update process are not retried. For a failed update, the VM rolls back to the agent version that it had before the update process started.
  9. Click Next.
  10. (Optional) On the Command Line tab, add any command line options.
  11. Click Finish.


  • A message displays at the top of the page indicating that the update has started.
  • The system updates the agent-related components on the desktop VMs in the dedicated VDI desktop assignment.
  • At the end of the agent update process, the assignment's summary page lists the version of the Horizon Agents Installer that is in effect.

You can view the progress of the update task by selecting Monitor > Activity. The task description indicates the update being performed and the assignment on which it is being performed. If the task is not completed successfully within 24 hours, and the retry and job timeout options are not in effect, the update task is shown in failure status.

If any VMs are skipped in the update task, the update task has Partial Success status on the Activity page. In the Activity page, you can see how many VMs are skipped in the update task. If you have a number of skipped VMs at the end of the update task even though the retry option was set to Yes, either the Job Timeout value was not long enough for the system to get to all of the skipped VMs or the end users never logged out of those VMs.