Skip to content

Connecting to Remote Desktops

Important: Welcome to our new user interface!

In release 22.09, the Software Client for macOS user interface was redesigned from the ground up. If you're a new user, you should find the new interface easy to follow; for existing users, note that some behavior has changed. Notes appear throughout this page when a task has changed from previous releases.

The Software Client for macOS can connect to any remote host with a PCoIP agent installed and configured, or a PCoIP Remote Workstation Card. Remote hosts can be Windows, macOS, or Linux, and can be made directly (client to host) or through a connection manager in enterprise deployments.

Note: PCoIP Remote Workstation Card connections

Connections to PCoIP Remote Workstation Cards require preparation on the remote machine before they will work. For details, see Preparing for PCoIP Remote Workstation Card Connections.

Creating Your First Connection

The first step is to create a connection to either your agent (for direct connections) or to your connection manager (for managed deployments).

  1. Launch the Software Client for macOS.

  2. If this is your first connection, the Software Client for macOS will prompt you to create one:

    No previously saved connections, add a new connection

    Click Add a new connection to proceed.

  3. In the Add New Connection pane, there are two fields to provide:

    Add a new connection

    • Host Address or Registration Code: Enter the address of the remote system you want to reach (you should have this information from your system administrator). This field accepts IP addresses, domain names, and registration codes, as in these examples:

      • An IP address: 123.456.789.012
      • A domain name: remote-desktops.example.com
      • A registration code: a1b2c3!@#

        Note: Amazon WorkSpaces registration codes

        If you are connecting to an Amazon WorkSpaces desktop, provide your WorkSpaces registration code in this field.

    • Connection Name: Provide a name for this connection. This can be anything; you will use this name to select this connection in future sessions. You can always change it later.

  4. Click Add connection.

Once this is done, you'll see the connection you created shown as a clickable button. You can add as many connections as you like, by clicking + Add a new connection at the bottom of the Connect pane.

Tip: Difference from previous workflows

The connections you save here are to brokers, or to direct desktop connections. If you have multiple desktops behind a single broker, you will still have to choose your desired desktop after authenticating with the broker. In the previous interface, you could save connections at any stage of the process, including to individual desktops.

If you have existing saved connections from previous releases, they will continue to work when you upgrade to this client version. However, if they are deleted, they cannot be re-created.

Connecting to a Session

  1. Assuming you have created at least one connection, the Software Client for macOS will now look something like this:

    Example connections

  2. Click the name of the connection you want. Next, provide your username and password:

    Authenticate request

    Note: About authentication credentials

    For managed connections, the authentication screen and validation that happens here is managed by your connection broker. The credentials are supplied to you by your system administrators, and are usually your corporate credentials.

    For direct connections where no broker is present, use the credentials for your user account on the remote machine.

  3. If your system is configured for multi-factor authentication, you will see a Multi-Factor Authentication screen next; either provide your passcode if you have one, or click Send Me a Push to have an authentication request sent to your registered device.

    MFA request

  4. Once your credentials are accepted, the Software Client for macOS shows you a list of your authorized desktops.

    Tip: Customizing desktop labels

    You can change the labels that appear in this list to make them easier to identify. See Changing the Remote Desktop labels for instructions.

    Choose a desktop

    Click the desktop you want to connect to.

Once you have selected your desktop, you will be connected to it and your PCoIP session will begin. The connection will use the display mode you last used (windowed, fullscreen one monitor, or fullscreen all monitors), unless altered by a launch-time configuration.

There may be a delay of a few seconds before you have control of your mouse and keyboard; this is normal.

Changing Remote Desktop Labels

By default, the Software Client for macOS displays the machine names of your remote desktops. These names can often be obscure strings that are difficult to identify or differentiate. You can modify the name shown in the desktop list to give them human-friendly names that are easier to understand.

Note: Only labels are changed

This procedure changes the desktop's label, shown in the client interface. It does not change the desktop's machine name.

To change the label for a desktop:

  1. Select a connection in the Software Client for macOS and provide your credentials.

  2. From the list of displayed desktops, find one you want to change and click its expansion icon to reveal the context menu:

    Changing the desktop label

  3. Click Rename.

  4. Provide the new, human-friendly name you'd like to see instead of the machine name.

  5. When finished, your desktops will appear using the name you specified:

    Desktop names have been changed

Restarting Remote Desktops

If your deployment supports remote restarts, you can command a desktop to restart from the Software Client for macOS pre-session interface (before you have connected to a PCoIP session).

Note: Not all deployments support this feature

The restart option will only be available if your system supports it. If it does not, the restart option will appear in the menu but will be disabled.

To restart a remote desktop:

  1. Select a connection in the Software Client for macOS and provide your credentials.

  2. From the list of displayed desktops, find one you want to restart and click its expansion icon to reveal the context menu:

    Restarting a desktop

  3. Click Restart.

The remote desktop will be restarted. Note that it will be unavailable for connections until the restart is complete, which may take several minutes depending on the system.

Viewing Information About Your Desktops

You can view detailed information about each of your available remote desktops, including resource names, IDs, and protocols.

Note: Resource names

If you have changed the desktop label as described above, you can find the original name by selecting the desktop info option and finding the resource name.

To view desktop info:

  1. From the list of displayed desktops, find the one you want to explore and click its expansion icon to reveal the context menu:

    Desktop info menu option

  2. Review the displayed information.

    Desktop info menu example

    To dismiss the info window, click OK or click the close button in the top corner.