WorkSpaces macOS client application - Amazon WorkSpaces
RequirementsSetup and installationDetermine your client versionConnect to your WorkSpaceManage your login information (3.0+ clients only)Client viewsClient languageDisplay supportProxy serversCommand shortcutsRemap the Windows logo key or the Command keyDisconnectClipboard supportDiagnostic log uploadRelease notes
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

WorkSpaces macOS client application

The following information helps you get started with the WorkSpaces macOS client application.

Requirements

  • The 4.0+ client and higher versions require macOS 10.15 (Catalina) to macOS 14 (Sonoma).

  • The 3.0+ client and higher versions require macOS 10.12 (Sierra) or later.

Important

If you use macOS 10.15 (Catalina) or later, you must use version 3.0.2 or later of the macOS client.

Note

  • If your WorkSpace is located in the Asia Pacific (Mumbai) Region, you must use version 3.1.3 or later of the Amazon WorkSpaces macOS client application.

  • WSP WorkSpaces are only supported with macOS client version 5.5.0 or higher.

Setup and installation

To download and install the client application, complete the following procedure.

To download and install the client application

  1. On your macOS device, open Amazon WorkSpaces Client Downloads and choose the MacOS X link.

  2. Download and install the application.

  3. Verify that the Amazon WorkSpaces client application icon appears on the desktop.

If you're having trouble updating your WorkSpaces macOS client application to a newer version, use the following procedure to update your client application.

To update the WorkSpaces macOS client application to a newer version

  1. In the Finder, open your Applications folder, then open Utilities, and choose Terminal.

  2. In the Terminal window, enter the following command, and then press the Return key.

    defaults delete com.amazon.workspaces SUSkippedVersion

  3. In the Terminal app, choose Terminal, Quit Terminal.

  4. If you have not already entered a registration code in the WorkSpaces macOS client application, do so, and then choose Amazon WorkSpaces, Quit Amazon WorkSpaces to close the client application.

  5. Restart the WorkSpaces macOS client application. You should be prompted to update the client. Accept the update.

Determine your client version

To see which version of the WorkSpaces client you have, choose Amazon WorkSpaces, About Amazon WorkSpaces, or click the gear icon in the upper-right corner and choose About Amazon WorkSpaces.

Connect to your WorkSpace

To connect to your WorkSpace, complete the following procedure.

  1. The first time that you run the client application, you are prompted for your registration code, which is contained in your welcome email. The WorkSpaces client application uses the registration code and user name to identify which WorkSpace to connect to. When you launch the client application later, the same registration code is used. To enter a different registration code, launch the client application, and then choose Change Registration Code at the bottom of the login page.

  2. Enter your sign-in credentials in the login screen and choose Sign In. If your WorkSpaces administrator has enabled multi-factor authentication for your organization's WorkSpaces, you are prompted for a passcode to complete your login. Your WorkSpaces administrator will provide more information about how to obtain your passcode.

  3. If your WorkSpaces administrator has not disabled the Keep me logged in feature, you can select the Keep me logged in check box at the bottom of the login screen to save your credentials securely so that you can connect to your WorkSpace easily while the client application remains running. Your credentials are securely cached up to the maximum lifetime of your Kerberos ticket.

    After the client application connects to your WorkSpace, your WorkSpace desktop is displayed.

An interruption of network connectivity causes an active session to be disconnected. This can be caused by events such as closing the laptop lid, or the loss of your wireless network connection. The WorkSpaces client application for macOS attempts to reconnect the session automatically if network connectivity is regained within a certain amount of time. The default session resume timeout is 20 minutes, but this timeout can be modified by your network administrator.

Manage your login information (3.0+ clients only)

You can view your registration code and what Region your WorkSpace is in. You can specify whether you want the WorkSpaces client application to save your current registration code, and you can assign a name to your WorkSpace. You can also specify if you want Amazon WorkSpaces to keep you logged in to a WorkSpace until you quit or your login period expires.

To manage your login information for a WorkSpace

  1. In the WorkSpaces client application, go to Settings, Manage Login Information.

  2. In the Manage Login Information dialog box, you can see the registration code and Region information for your WorkSpace.

  3. (Optional) If you want the WorkSpaces client to remember your current registration code, select the Remember Registration Code check box.

  4. Under Saved registration codes, select the WorkSpace you want to name.

  5. In the WorkSpace name box, enter a name for the WorkSpace.

  6. (Optional) If you want WorkSpaces to keep you logged in until you quit or your login period expires, select the Keep me logged in check box.

  7. Choose Save.

Client views

You can switch to full screen mode by choosing View, Enter Full Screen (3.0+ clients) in the client application menu.

While in full screen mode, you can switch back to window mode by moving the pointer to the top of the screen. The client application menu is displayed, and you can choose View, Leave Full Screen (3.0+ clients) in the client application menu.

You can also toggle full screen mode by pressing Command+Option+Return.

Client language

You can select the language displayed by the client by performing the following steps.

Note

The WorkSpaces client applications support Japanese. However, Japanese WorkSpaces are available only in the Asia Pacific (Tokyo) Region.

To select the client language

  1. Depending on which client you're using, do one of the following.

    If you're using... Do this

    3.0+ client

    In the WorkSpaces client application, go to Settings, Change Language.

  2. Enter your desired language in the Select a language list and choose Save.

  3. Restart the client.

Display support

WorkSpaces Value, Standard, Performance, Power, PowerPro, and GraphicsPro bundles support a maximum of four displays and a maximum resolution of 3840x2160 (ultra-high definition, or UHD). The maximum supported resolution depends on the number of displays, as shown in the following table.

Displays Resolution

2

3840x2160

4

1920x1200
Note

  • You can only extend the display. You cannot duplicate the display. Duplicating the display will cause your session to be disconnected.

  • Graphics bundles support only a single monitor configuration with a maximum resolution of 2560x1600.

The WorkSpaces client application extracts the Extended Display Information Data (EDID) of all attached displays and determines the best compatibility match before starting the session. If you have a high pixel density (high DPI) display, the client application automatically scales the streaming window according to your local DPI settings. For better maximum resolution with high DPI displays, see WorkSpaces high DPI display support.

Note

If your screen resolution in WorkSpaces is low and objects look blurry, you need to turn on high DPI mode and adjust the display scaling settings on your Mac. For more information, see WorkSpaces high DPI display support.

To use multiple monitors with WorkSpaces

  1. Configure your local machine to use multiple monitors. For more information, see Use multiple displays with your Mac in the Apple documentation.

  2. Start the WorkSpaces client application and log in to your WorkSpace.

  3. Depending on which client you're using, do one of the following:

    If you're using... Do this
    3.0+ client Choose View, Enter Full Screen On All Displays. You can also toggle full screen mode by pressing Command+Option+Return.

Your WorkSpace should now be extended across your displays. Whichever display you have designated as your primary display is also the primary display in WorkSpaces when you enter full screen mode.

Note

To use full screen mode on only some of the displays in a multiple monitor setup, press and hold the Option key and then click the green maximize button Maximize button in the top-left corner of the WorkSpaces window. This button expands the WorkSpaces client window to full size on a screen without extending the WorkSpace to the other displays. To return to the previous window size, press and hold the Option key and click the maximize button again.

Proxy servers

If your network requires you to use a proxy server to access the internet, you can enable your WorkSpaces client application to use a proxy for HTTPS (port 443) traffic. The WorkSpaces client applications use the HTTPS port for updates, registration, and authentication.

Note

  • The desktop streaming connections to the WorkSpace require ports 4172 and 4195 to be enabled, and do not go through the proxy server.

  • Proxy servers that require authentication with a sign-in credentials are not supported.

By default, the 3.0+ macOS clients use the proxy server that's specified in the device operating system settings. The first time the client is launched, the device operating system proxy server setting is used. If you select another option for the proxy server, that setting is used for subsequent launches of the client.

Note

If you specify a custom proxy server, a "No network" error might appear when you attempt to log in to your WorkSpace. To work around this issue, use the default operating system proxy server instead of specifying a custom proxy server in the macOS client.

  1. In the WorkSpaces client application, go to Settings, Manage Proxy Server.

  2. In the Set Proxy dialog box, select Use proxy server, enter the proxy server URL or IP address and the port, and choose Save.

Command shortcuts

The WorkSpaces macOS client supports the following command shortcuts:

If you're using... Use these shortcuts

3.0+ client

Command+Q—Quit Amazon WorkSpaces

Command+Option+Return—Toggle full screen display

Command+Option+F12—Disconnect session

Remap the Windows logo key or the Command key

By default, the Windows logo key on a Windows keyboard and the Command key on an Apple keyboard are both mapped to the Ctrl key when you're using the Amazon WorkSpaces macOS client application. If you want to change this behavior so that these two keys are mapped to the Windows logo key for use with Windows WorkSpaces, use the following procedure.

To map the Windows logo key or the Command key to the Windows logo key

  1. If you haven't already done so, install or update to version 3.0.5 or later of the Amazon WorkSpaces macOS client application.

  2. In the Finder, open your Applications folder, then open Utilities, and choose Terminal.

  3. In the Terminal window, enter the following command, and then press the Return key.

    defaults write "com.amazon.Amazon WorkSpaces Client" remap_cmd_to_ctrl 0

  4. In the Terminal app, choose Terminal, Quit Terminal.

  5. If your WorkSpaces macOS client application is running, choose Amazon WorkSpaces, Quit Amazon WorkSpaces in the client to close the client application.

  6. Restart the WorkSpaces macOS client application and log in to your WorkSpace. The Windows logo key or the Command key should now be mapped to the Windows logo key.

Disconnect

To disconnect the macOS client application, you have several options:

  • In the Amazon WorkSpaces client application, go to Amazon WorkSpaces, and then choose Disconnect WorkSpace. Your WorkSpace session ends, but the client application continues running in case you want to log in again.

  • In the Amazon WorkSpaces client application, go to Amazon WorkSpaces, and then choose Quit Amazon WorkSpaces. Your WorkSpace session ends, and the client application closes.

  • In the Amazon WorkSpaces client application, close the WorkSpaces client window by clicking the red close (X) button in the upper-left corner. In the End Session dialog box, choose Yes. Your WorkSpace session ends, but the client application continues running in case you want to log in again.

  • You can also log off of the WorkSpace. In the Amazon WorkSpaces client application, go to View, and then choose Send Ctrl+Alt+Delete. Choose Sign Out. Your WorkSpace session ends, but the client application continues running in case you want to log in again.

Clipboard support

The clipboard supports a maximum uncompressed object size of 20 MB. For more information, see I'm having trouble copying and pasting.

Note

When copying from a Microsoft Office app, the clipboard only contains the last copied item, and the item is converted into standard format. If you copy content larger than 890 KB from a Microsoft Office app, the app might become slow or unresponsive for up to 5 seconds.

Diagnostic log upload

Enabling diagnostic log uploads

To troubleshoot issues with the WorkSpaces client, you can enable diagnostic logging. The log files that are sent to WorkSpaces include detailed information about your device and connection to the Amazon network. You can enable diagnostic log uploads before or during WorkSpace streaming sessions so that these files are sent to WorkSpaces automatically.

To send log files:
Note

You can send log files before and during WorkSpaces streaming sessions.

  1. Open your Amazon WorkSpaces client.

  2. At the top of the WorkSpaces sign-in page, choose Manage Diagnostic Logging Settings.

  3. In the pop-up dialog box, choose Enable Diagnostic Logging for Amazon WorkSpaces and click Save.

    Important

    When you report an issue to Amazon support, ensure you keep track of the device ID of the client who is experiencing the issue. This device ID can be found in the diagnostics logging menu, in the WorkSpaces client navigation bar, and it helps the support team identify logs associated with your specific device. Ensure you include the device ID in the tickets that you create regarding this specific issue.

Release notes

The following table describes the changes to each release of the client application.

Release Date Changes
5.19.0 February 28, 2023

  • Added WebAuthn support for in-session authentication.

  • Resolved a white screen issue for WSP WorkSpaces.

  • Fixed the pixelation issue for WSP WorkSpaces.

  • Resolved crash issues for WSP WorkSpaces.

  • Updated WSP SDK.
5.18.0 January 22, 2023

  • Updated PCoIP SDK.

  • Updated WSP SDK.

  • Added support for macOS 14 (Sonoma).

  • Fixed keyboard issue where the first keystrokes were not being transmitted after unlocking the screen.
5.17.0 November 16, 2023

  • Fixed a login issue due to a custom proxy error on macOS Ventura.

  • Added support to configure option key behavior on WSP client.

  • Fixed a client crash when users change running mode.

  • Fixed the screen freezing issue when using a Smart Card on WSP client.

  • Improve stability during resizes on WSP client.

  • Improved visual accessibility.
5.16.0 October 26, 2023

  • Improved visual accessibility.

  • Updated WSP SDK.
5.15.1 September 20, 2023

  • Enabled persistent Webcam connection after fast WSP WorkSpace reconnection.

  • Fixed connectivity issues on WSP WorkSpaces when using a proxy server.

  • Updated WSP SDK.

  • Bug fixes and enhancements.
5.12.0 August 29, 2023

  • Updated PCoIP SDK and WSP SDK.

  • Resolved an login page special character processing issue.

  • Added a link to Amazon WorkSpaces user guide under the Support menu.
5.11.0 June 29, 2023

Added options to enable or disable Ctrl + left-click as right-click and enable or disable mapping the Command key to the Ctrl key. To access both options, from the menu bar, choose Settings, Manage Modifier Keys.
5.10.0 June 19, 2023

  • Improved client custom branding by storing assets in the same Amazon Regions as provisioned WorkSpaces.

  • Resolved black screen issue when using multiple monitors with Ubuntu WorkSpaces.

  • Fixed client diagnostic log uploading issues, where proxy settings were not being persisted when connecting to WorkSpaces through a proxy server.

  • Added support for NICE DCV extension SDK, which allows end users to customize their WSP WorkSpaces experience.
5.9.0 May 9, 2023 Updated WSP SDK to fix playback volume issues.
5.8.0 April 6, 2023

  • Added accessibility improvements.

  • Added support for automatic diagnostic log uploads feature, which allows you to upload WorkSpaces client log files directly to WorkSpaces to troubleshoot issues without interrupting the use of the WorkSpaces client.

  • Updated the WSPv2 SDK to fix InSessionLatency reporting.
5.7.0 February 23, 2023

  • Updated the WSP SDK.

  • Enabled trimming leading or trailing allow list in sign-in credentials.
5.6.0 December 27, 2022

  • Added support for certificate-based authentication via SAML 2.0 integration, which removes the logon prompt for the Active Directory domain password.

  • Resolved the issue of the Workspace menu bar being inaccessible when maximizing the Workspace application window.

  • Updated PCoIP SDK for the WorkSpaces macOS client.
5.5.0 November 14, 2022 Updated the WSP client SDK.
5.4.0 November 10, 2022 Added a shortcut Command+Alt+F12 to disconnect your WorkSpaces.
5.3.0 September 15, 2022

Bug fixes and enhancements.
5.2.0 August 24, 2022

Fixed WorkSpaces login issue when using Smart Card.
5.1.0 June 30, 2022

Updated PCoIP SDK for MacOS.
4.0.7 March 3, 2022 Fixed a WorkSpaces connection error caused by the Proxy settings on MacBook.
4.0.6 December 21, 2021

  • Resolves crashes and black screen issues related to video streaming for WSP

  • Updates to WSP version 1.9.8.18175
4.0.5 November 23, 2021

  • Optimizes the bandwidth and frame rates for WSP WorkSpaces

  • Resolves the shortcut mapping issue related to full screen mode
4.0.4 November 3, 2021

  • Resolves the spinning wheel problem on the Login screen in macOS Big Sur with PCoIP WorkSpaces

  • Video streaming improvements for WorkSpaces that support WSP

  • Bug fixes
4.0.3 October 4, 2021 Bug fixes and enhancements.
4.0.2 September 8, 2021 Minor bug fixes and enhancements.
4.0.1 August 5, 2021 Minor bug fixes and enhancements.
3.1.9 June 29, 2021 Minor bug fixes and enhancements.
3.1.8 May 28, 2021

  • Addresses a crash issue after disconnecting from PCoIP WorkSpaces

  • Addresses a connectivity issue with WSP WorkSpaces on M1 Mac hardware

  • Minor bug fixes and enhancements
3.1.7 April 29, 2021

  • Improves connectivity with WorkSpaces using the WorkSpaces Streaming Protocol (WSP)

  • Minor bug fixes and enhancements
3.1.6 April 8, 2021

Fixes for disconnects and crashes resulting from WorkSpaces Streaming Protocol (WSP) audio traffic optimization
3.1.5 April 2, 2021

  • Adds in-session and pre-session support for Common Access Card (CAC) and Personal Identity Verification (PIV) smart cards with WSP Windows WorkSpaces

  • Bidirectional video webcam support is now generally available for Windows WorkSpaces using the WorkSpaces Streaming Protocol (WSP)

  • Minor bug fixes and enhancements
3.1.4 March 16, 2021

  • Addresses a few crash scenarios when users register, log in, and rebuild

  • Adds localization support for more UI elements

  • Minor bug fixes and enhancements
3.1.3 February 15, 2021

  • Adds support for mouse middle button dragging

  • Minor bug fixes and enhancements
3.1.2 January 8, 2021

  • The WorkSpaces Streaming Protocol (WSP) is now generally available. Video-in functionality continues to be available as a beta feature on WSP WorkSpaces only

  • Minor bug fixes and enhancements
3.1.0 December 1, 2020

Minor bug fixes and enhancements
3.0.12 November 10, 2020

  • Adds enhancements to the session reconnect experience

  • Improves error messaging during session disconnects for WorkSpaces Streaming Protocol (WSP) WorkSpaces

  • Fixes keyboard mapping issue with the Shift key for WSP WorkSpaces

  • Fixes an issue in the device-enumeration logic where video-in devices might not be shown on subsequent logins for WSP WorkSpaces
3.0.11 October 02, 2020

  • Resolves an intermittent crash issue when disconnecting from a WorkSpaces Streaming Protocol (WSP) WorkSpace

  • Minor bug fixes and enhancements
3.0.10 September 16, 2020

Adds support for health checks over port 4195 (UDP and TCP)
3.0.9 August 14, 2020

Minor bug fixes and enhancements
3.0.8 July 30, 2020

  • For improved diagnostics, displays round trip time (RTT) as part of the network health check information

  • Minor bug fixes and enhancements

3.0.7

 June 3, 2020

  • Adds support for multiple monitors on WorkSpaces Streaming Protocol (WSP) WorkSpaces

  • Minor bug fixes and enhancements

3.0.6

 April 28, 2020

  • Adds support for toggling between high DPI and standard DPI displays

  • Minor bug fixes and enhancements

3.0.5

 March 30, 2020

  • Resolves an issue with the user interface displaying a login prompt if single sign-on (SSO) is enabled for Amazon WorkDocs

  • Adds support to map the Command key to the Windows logo key

3.0.4

 March 3, 2020

  • Adds support for connecting to WorkSpaces Streaming Protocol (WSP) WorkSpaces

  • Minor bug fixes and enhancements

3.0.3

 February 24, 2020

Improves readability on high DPI devices

3.0.2

 February 14, 2020

  • Adds keyboard shortcut to toggle full screen display

  • Minor bug fixes and enhancements

3.0.0

 November 25, 2019

  • Improved user interface

  • Friendly registration code labels

  • Client-side GPU rendering

  • Minor bug fixes and enhancements

2.5.11

 November 4, 2019

  • Resolves issues with support for the macOS Catalina keyboard

  • Minor bug fixes

2.5.9

Minor bug fixes

2.5.8

  • Resolves an intermittent crashing issue related to computer waking up when opening a laptop lid

2.5.7

  • Adds support for German keyboard layouts with Linux WorkSpaces

  • Resolves an issue that results in a crash of Excel with clipboard direction

2.5.6

Minor fixes

2.5.5

  • Resolves an issue with sub-optimal resolution with external displays in full-screen mode connected using USB-C

  • Minor bug fixes

2.5.2

  • Resolves an issue that results in crashes when multiple monitors are used and clients are connected to WorkSpaces running Amazon Linux 2

  • Resolves an intermittent issue with the Caps lock key becoming stuck

  • Minor bug fixes

2.5.1

  • Resolves an issue that periodically results in repeated key presses with WorkSpaces running Amazon Linux 2

  • Adds support for localized date and time formats in the user interface

  • Adds handling for URIs that end with an extra '/'

  • Minor user interface improvements

2.5.0

Adds support for user self-service WorkSpace management capabilities

2.4.10

Minor fixes

2.4.9

Minor fixes

2.4.8

  • Adds support for uniform resource identifiers (URIs), which enable login orchestration

  • Improves the behavior of function (Fn) keys on macOS

  • Improves protocol handling

  • Minor fixes

2.4.7

  • Adds support for time zone redirection for more Regions: America/Indianapolis America/Indiana/Marengo America/Indiana/Vevay America/Indiana/Indianapolis

  • Includes text changes to the Login page user interface

2.4.6

  • Adds support for configuring the logging level to include advanced logging for debug scenarios

  • Minor improvements to session provision handling

  • Increases error handling for keyboard connections

2.4.4

  • Minor fixes

  • Improves copy and paste

2.4.2

Minor fixes

2.4.0

  • New logo

  • Improves the user interface and stability

2.3.7

  • Addresses a gray screen issue that occurs when displays are in different orientations

  • Resolves a crashing issue on macOS

2.3.6

Localization enhancements

2.3.5

Minor improvements

2.3.3

  • Improves support for multiple monitors

  • Localization enhancements

  • Improves security and performance

2.3.1

Minor fixes

2.3.0

  • Improves support for multiple monitors

  • Improves security and stability

2.2.3

Resolves minor bugs and improves stability

2.2.1

  • Adds support for the German language

  • Resolves issues with time zone mapping for some Regions

  • Resolves a connection issue on Russian systems

  • Improves the Japanese user interface

  • Improves stability

2.1.4

Resolves a crash issue on macOS Sierra

2.1.3

Closing the client expires the reconnect token. You can easily reconnect to your WorkSpace as long as the client is running.

2.1.0

  • Adds support for the following new WorkSpace states: STOPPING and STOPPED

  • Resolves minor bugs and improves stability

2.0.8

  • Resolves an issue with out-of-app keyboard input passing to WorkSpaces

  • If Remember Me is disabled, the user name is not shown on restart

  • Adds a confirmation dialog box when deleting a registration code

  • Improves stability

2.0.4

  • Adds support for audio in, enabling you to make calls or attend web conferences

  • Adds support for devices with high DPI screens

  • Adds support for saving registration codes, enabling you to switch WorkSpaces without re-entering the registration codes

  • Improves support for OS X El Capitan

  • Improves usability and stability

1.1.80

  • Adds CloudWatch metrics for session latency, session launch time, and session disconnects

  • Improves auto session resume so that you are interrupted less frequently when network conditions are degraded

  • Resolves specific issues and improves stability

1.1.6

  • Adds support for status notifications. The client application notifies you about the state of your WorkSpace when it cannot connect to the WorkSpace.

  • Improves the reconnect experience. The client automatically redirects to the login screen after 10 hours of inactivity. You can reconnect again if the client fails to launch a session using reconnect.

  • Adds support for auto session resume. The client application automatically attempts to resume your session if network connectivity is lost and then regained within the session resume timeout (default value is 20 minutes).

  • Improves network health checks so they are faster and more reliable

  • Adds client-side validation of registration codes

  • Improves the synchronization of Caps Lock and Num Lock status between the local device and the WorkSpace

1.1.4

  • Adds support for saving your credentials, enabling you to easily reconnect to your WorkSpace

  • Improves advanced connection health checks

  • Improves stability

1.0.8

  • Introduces a full-file installation package

  • Improves network connectivity checks

  • Adds version information to the About window

1.0

Initial release