Install Tehama Client on Mac

  • Updated
Follow

Install Tehama Client on Mac

Latest available Tehama Client version for Mac: 2.4.0

Downloaded from: the Tehama Web UI, current release

Supported macOS versions: Mojave to Monterey

 

This guide contains two parts:

Installation workflow

There are four steps to installing the Tehama Client on your Mac device.

Note: These instructions have been tested on and optimized for the Google Chrome browser.

 

 download client

  1. Log in to the Tehama Web UI.
  2. Go to the DESKTOPS page.
  3. Click on the INSTALL CLIENT button in the top right of the page. This page provides you with information about the Tehama Client.
  4. Click on the download link next to the Apple symbol.
  5. Wait for the tehama_pcoip_client.dmg file to be downloaded to your Downloads folder.

 

 uninstall previous client

You can skip this step if your device has never had an earlier version of the Client installed on it.

It is strongly suggested that you first uninstall the current Client (both the Tehama Client and the Teradici PCoIP Client) from your device, then restart your device before installing the new version.

  1. Remove ‘Tehama’ and ‘PCoIPClient’ from your Applications folder (move them to Trash).
  2. Make sure ‘applet’, a residual client application, is removed from your device's Accessibility settings, as follows:
    1. Open the Security & Privacy modal, from System Preferences.
    2. Click on the 'Privacy' tab.
    3. Select 'Accessibility' from the sidebar menu. This shows the list of apps that are allowed to control your computer.
    4. Locate 'applet' in the list.
    5. Click the lock the make changes (you will need to provide authorization).
    6. Place a checkmark in the checkbox next 'applet'.
    7. Click on minus sign to remove 'applet'.
    8. Click the lock to prevent any more changes. (Only need to do this after the last one.)
      Remove the 'applet' residual application from your device's Security & Privacy 'Accessibility' list.
  3. Restart your device.

 

 install new client

  1. Go to your Downloads folder.
  2. Double-click on tehama_pcoip_client.dmg.
  3. Read through the SOFTWARE LICENSE AGREEMENT.
  4. Click on "Agree", if you wish to accept the agreement and proceed.
  5. Observe the dialog with text "Drag and drop both apps into Applications folder to install" appears.
  6. Left click and hold on the "Tehama.app" symbol, drag it over the "Applications" symbol and release.
  7. Left click and hold on the "PCoIPClient.app" symbol, drag it over the "Applications" symbol and release.
  8. Dismiss the dialog.

The Client is installed on your device, but still needs to have its permissions configured. This is done the during the first time you attempt to connect to a Tehama Desktop with your newly installed client. Continue on to STEP 4 to do that now.

 

 configure client permissions

This step configures the Client permissions needed to ensure that peripherals, accessories like your keyboard and mouse, function properly with your Tehama Desktop.

If you intend to use an extended keyboard with your Tehama Desktop, you may also need to configure additional Client permissions by following the instructions in the section "The number pad from my extended keyboard is not working inside the Tehama Desktop" after you have finished this step.

  1. Open your browser, if it is not already open.
  2. Ensure that your browser does not block the Tehama Client pop-up.
    When connecting to a Desktop, the Tehama Client is launched through a pop-up in your browser. If you attempt to connect to your Desktop using a browser that does not allow the Tehama Client pop-up, then the browser will block the Tehama Client pop-up, and it will not be able to launch. Go into the settings for your chosen browser and make sure that the browser from which you intend to connect to your Desktop allows this pop-up from https://<your-org-subdomain>.tehama.io:443. (Each browser configures pop-up controls differently. Query your browser's help to determine the correct procedure.)

    NOTE: In some browsers, it is obvious when a pop-up is being blocked. In others, it is less obvious. For example:
    • In Firefox, a banner will appear at the top of the page stating that Firefox prevented the site from opening the pop-up. Click on the "Options" button on the banner to view your pop-up options.
    • In Google Chrome, the indication that a pop-up is being blocked is a small icon with a red X that appears in the browser's address bar. Click on that icon to allow pop-ups.
  3. Log in to the Tehama Web UI, if you are not already logged in.
  4. Navigate to the DESKTOPS page. (From the TEHAMA CLIENT page, just click CLOSE X.)
  5. Locate your Tehama Desktop in the list of desktops.
  6. Connect to your desktop with one-click by clicking on the CONNECT button.
  7. A new tab will appear, asking you if you want to "Open Tehama.app?".
  8. Click on "Open Tehama.app".
  9. You should see a prompt with the following message: '"applet" would like to control this computer using accessibility features. Grant access to this application in Security & Privacy preferences, located in System Preferences.'
    If you do not see this prompt, try following the alternate method for configuring Client permissions in section "My keyboard is not working inside the Tehama Desktop".
    Place a checkmark in the checkbox beside 'applet' in your device's Security & Privacy 'Accessibility' list.
    At this point:
    1. Click Open System Preferences. The Security & Privacy modal will appear, open to the 'Accessibility' list of apps. You should see the 'applet' application in the Accessibility list.
    2. Place a checkmark in the checkbox beside 'applet'.
      Place a checkmark in the checkbox beside 'applet' in your device's Security & Privacy 'Accessibility' list.
      Now the Client is configured. NOTE: This configuration only takes effect the next time you connect to your Tehama Desktop.
  10. Restart your Tehama Desktop. (Close your current session and re-connect to a new session.)

 

Post installation issues/enhancements

After you have installed the Tehama Client, you should be able to launch and use your Tehama Desktop.

This section describes how to solve issues some users may experience with the Tehama Client on Mac.

This section also contains Tehama Client configuration enhancements, like how to remap the behaviour of Command+C/V to be the same in your Mac device and on your Tehama Windows Desktop.

 

 keyboard not working

If you are experiencing problems with your keyboard when in a Tehama Desktop session on your Mac device, the most likely explanation is that the Client permissions on your device are not configured appropriately. Possibly the usual method of configuring Client permissions may not have worked for you. Try following these alternate instructions to help you resolve the issue.

  1. Uninstall your Client from your device. (Follow the instructions above in section "Uninstall previously installed Clients".)
  2. Then re-install the Client on your device. (Follow the instructions above to "Install the new version of the Client".)
  3. Make sure your device's 'Accessibility' list does not contain any residual Tehama Client-related applications. You should not see 'applet', 'Tehama', or 'PCoIPClient' on the list.
    1. Open the Security & Privacy modal, from System Preferences.
    2. Click on the 'Privacy' tab.
    3. Select 'Accessibility' from the sidebar menu. This shows the list of apps that are allowed to control your computer.
    4. Look for 'applet', 'Tehama' and 'PCoIPClient'.
    5. For each of these apps that you find,
      • Click the lock the make changes (you will need to provide authorization). (Only need to do before the first one.)
      • Place a checkmark in the checkbox next 'applet'.
      • Click on minus sign to remove 'applet'.
      • Click the lock to prevent any more changes. (Only need to do this after the last one.)
        Remove all residual Client artifacts from your device's 'Accessibility' list.
  4. Go to your Applications folder, right-click on ‘Tehama’, and ‘Show Package Contents’.
    Navigate to your Client app ('Tehama') package contents.
  5. The next step depends on your device's macOS version:
    • If your macOS version is Big Sur.
      • Find ‘applet’ from the path "Contents -> MacOS -> applet", and drag this ‘applet’ to Accessibility.
        Navigate to your Client app ('Tehama') applet application.
        Drag the applet application to the 'Accessibility' list.
    • If your macOS version is Catalina or lower.
      • Find ‘Tehama’ from the path "Contents -> MacOS -> Tehama", and drag this ‘Tehama’ to Accessibility.
        Navigate to your Client app ('Tehama') Tehama application.
        Drag the Tehama application to the 'Accessibility' list.
  6. Normally the ‘applet’ or ‘Tehama’ from the previous step should be checked, if not, check the checkbox.
  7. Click the lock (in the Security & Privacy modal) to prevent any more changes.
  8. Connect to your Tehama Desktop to try it out. (If you have an open Desktop session, close it and reconnect.)

Your keyboard should be working at this point.

 

 extended number pad not working

The Tehama Client allows you to use your peripheral devices with it, so you can get the most out of your Tehama desktop.

An important peripheral device is an extended keyboard, a keyboard with a number pad. A small number of Tehama Desktop users may need to run through the following instructions to configure additional Client permissions in order to use this peripheral with the Client on their Mac devices.

It is assumed that you have already installed the Client, following the instructions in the Installation Workflow.

  1. Add PCoIPClient into your Accessibility list, and make sure everything is checked on that list.
    1. Open the Security & Privacy modal, from System Preferences.
    2. Click on the 'Privacy' tab.
    3. Select 'Accessibility' from the sidebar menu. This shows the list of apps that are allowed to control your computer.
    4. Click the lock to make changes (you will need to provide authorization).
    5. Click on the plus sign to add a new application to the list. A file system browser modal will appear.
    6. Navigate in the Finder app to the Applications folder.
    7. Select the PCoIPClient application.
    8. Click the Open button. The PCoIPClient application will now be in the Accessibility list.
    9. Place a checkmark in the checkbox beside PCoIPClient, if it is not already checked.
    10. Click the lock to prevent any more changes.
    The following short video shows this sequence of steps.
    Drag the PCoIPClient application to the 'Accessibility' list.
  2. Connect to your Tehama Desktop to try it out. (If you have an open Desktop session, close it and reconnect.)
  3. Try clicking the clear key once when you are inside a Tehama Windows Desktop, to verify that you can now use the extended keyboard.
    Click on the clear key in the extended number pad from inside a Tehama Desktop session.

 

 Mac control vs command in Tehama Windows Desktop

By default, the keyboard is mapped to align with the operating system you are using. For example, if you use Tehama Windows Desktops from a MacBook, due to the difference between Windows and macOS on their control/command keys, your experience will be as follows:

  • When you are inside the Tehama Windows desktop, Control+C/V is used for copy/paste
  • When you are on your local MacBook, Command+C/V is used for copy/paste

If you would like to remap this experience to use Command+C/V for both macOS and Tehama Windows Desktop, please do the following:

 

  • Open Terminal on macOS.
  • Run the following command line one by one in Terminal: 
    defaults write "com.teradici.Teradici PCoIP Client" mac_capture_all_keys 0 
    defaults write "com.teradici.Teradici PCoIP Client" mac_system_shortcut_capture 0 
    defaults write "com.teradici.Teradici PCoIP Client" remap_cmd_to_ctrl 1
    The last line ensure the 'command' key maps to the 'Ctrl' key on your Tehama Windows desktop.
  • Connect to your Tehama Desktop to try it out. (If you have an open Desktop session, close it and reconnect.)

 

Related articles