Control the WorkSpaces client experience for your users

Starting on August 25, 2026, Amazon WorkSpaces is introducing a new WorkSpaces Windows client with an updated interface, designed to be easier to use, with a simplified connection flow, easier-to-find settings and session tools, more helpful error messaging, and a new Session Health feature.

The new experience (referred to as "new" in the rest of this document) will be included in the client application installer package starting in version 5.34, and will install and run alongside the current experience (referred to as "classic").

By default, your end users on the Amazon WorkSpaces Windows client will see an option to "Try out" the new experience after they select a WorkSpace to connect to. If they click on this option, they will see a confirmation dialog explaining what to expect, and if they continue, the classic experience will close, and the new experience will open within a few seconds. Likewise, in the new experience, they will see an option to "Switch back to classic" at any time. While we highly encourage you to allow the default behavior, we're introducing a Client Experience Policy feature in case you need to manage the rollout of the new client experience for your end users.

As an administrator, using the Client Experience Policy, you can control which experience your users see, and whether they can switch between the two. The policy is available now — so you can decide how the new experience rolls out to your users and put the behavior you want in place before the new client launches.

This topic explains the available policy values, how to set the policy through the WorkSpaces API or through the Windows registry, and how the client resolves the policy when a user connects.

How the Client Experience Policy works

The Client Experience Policy determines which client experience a user sees when they connect to a WorkSpace, and whether the option to switch experiences is available to them.

You can set the policy at two levels:

If you take no action, the policy defaults to USER_CHOICE: your end users using the Amazon WorkSpaces Windows client version 5.34 or higher will default to the classic experience but can opt into the new experience themselves, by clicking on the "Try out" option in the client.

Policy values

The Client Experience Policy accepts the following values.

Policy resolution order

When a user selects a WorkSpace to connect to, the client resolves the effective policy by checking each source in the following order. The first source that has a value set wins and supersedes all lower-priority sources. If neither the API nor the registry has a value set, the client applies the default USER_CHOICE behavior.

When the policy takes effect

The client applies the policy in the pre-session phase — after a user selects a WorkSpace to connect to, but before they sign in. Switching experiences requires a client restart. If the resolved experience differs from the one currently running, the client will prompt the user to restart the client in order to proceed connecting to their selected WorkSpace. The policy is not evaluated during an active session. If you change a policy while a user is connected, the change takes effect the next time the user starts the client or signs out and back in.

Option 1: Set the policy through the WorkSpaces API

Use the ModifyClientProperties API operation to set the policy for a directory. The ClientExperiencePolicy field is part of the ClientProperties object.

AWS CLI example

The following command sets the policy for a directory to USER_CHOICE, allowing users to choose their experience:

aws workspaces modify-client-properties \
    --resource-id d-1234567890 \
    --client-properties ClientExperiencePolicy=USER_CHOICE

To force all users in a directory to the new experience:

aws workspaces modify-client-properties \
    --resource-id d-1234567890 \
    --client-properties ClientExperiencePolicy=FORCE_UI_2026

View the current policy

Use the DescribeClientProperties API operation to view the policy currently set for a directory:

aws workspaces describe-client-properties \
    --resource-ids d-1234567890

The response includes the ClientExperiencePolicy field if a policy has been set. If no policy has ever been set for the directory, the field is omitted and the client falls back to the machine-level registry policy (if set) or the default USER_CHOICE behavior.

{
    "ClientPropertiesList": [
        {
            "ResourceId": "d-1234567890",
            "ClientProperties": {
                "ReconnectEnabled": "ENABLED",
                "LogUploadEnabled": "ENABLED",
                "ClientExperiencePolicy": "USER_CHOICE"
            }
        }
    ]
}

Option 2: Set the policy through the Windows registry

If you manage client machines centrally, you can set a per-machine policy using the following registry value. Deploy it through Group Policy or a configuration management tool.

Path:  HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\Amazon WorkSpaces Client
Name:  ClientExperiencePolicy
Type:  REG_SZ
Value: FORCE_CLASSIC | FORCE_UI_2026 | USER_CHOICE

This registry path is consistent with other WorkSpaces client machine settings, such as clientUpgradeDisabled and WSUseDualStackIPv6.

To set the value from an elevated command prompt, use the following command. This example forces the new experience:

reg add "HKLM\SOFTWARE\Amazon\Amazon WorkSpaces Client" /v ClientExperiencePolicy /t REG_SZ /d FORCE_UI_2026 /f

To remove the value:

reg delete "HKLM\SOFTWARE\Amazon\Amazon WorkSpaces Client" /v ClientExperiencePolicy /f

The registry policy applies only when no per-directory API policy is set for the directory the user connects to. A per-directory API policy always takes precedence over the machine-level registry policy.

What your users will experience

Plan your rollout

We recommend the following approach when adopting the new experience:

Related topics