macOS
Overview
The HYAS Protect Agent (HPA) empowers organizations to leverage the robust capabilities of HYAS Protect on their roaming devices. Functioning as a DNS Proxy, the HPA offers a straightforward, lightweight, and highly effective solution to extend the full benefits of HYAS Protect to your mobile workforce.
This page will review the HPA installation procedure for a Mac machine. We’ll give you both UI and Terminal options along with some troubleshooting steps if you get stuck along the way.
Architecture
The HPA consists of two parts, a service and a UI (user interface)
Service/Backend: The service, also known as the backend, is responsible for the core functionality and logic of the Agent.
The UI, also known as the front end, is the part of the application that users interact with.
For purposes of this document, when referring to the HPA, we mean the service and the UI together.
Agent Deployment
If your organization uses local domains, please be sure to configure Local Domains PRIOR to deploying the HPA.
If your organization uses a VPN, please review VPN Compatibility testing below PRIOR to deploying the HPA.
Downloading the Agent - HYAS Protect UI
HYAS makes it simple to download the macOS HPA directly through the UI.
Log into the HYAS Protect UI.
Navigate to the Settings icon
Select ‘Organization Settings’
Finally, select 'Protect Agent' from the menu on the left side.
From the Protect Agent dashboard, select the ‘Install’ tab.
Click the macOS download button to begin the download.
Downloading the Agent - Terminal
In certain scenarios, it may be preferable to download the HPA via terminal. The instructions below guide you through that process.
Administrator privileges are required to install via Terminal.
Verify the latest version of the macOS Agent.
Navigate to the HYAS Protect UI, Settings>Protect Agent> Install. The download buttons confirm the latest Agent version number.
Copy the curl command below and paste into the macOS terminal.
curl https://protect-updates.hyas.com/macos/pkg/HYAS-Protect-latest.pkg -o $HOME/Downloads/HYAS-Protect-latest.pkg
The HPA has now been downloaded to your local ‘Downloads’ folder.
Installing the Agent - Interactive
Now that you’ve downloaded the Agent, its time to install it. This walks you through how to complete an interactive install. Instructions on a silent install in the next section.
Navigate to your downloads folder and double click the HYAS-Protect-latest.pkg file.
Follow the steps in the Setup Wizard below:
Click “Allow”
Click “Continue”
Paste your Install Key and then here then click, “Continue”
To obtain your Install Key, navigate to the HYAS Protect UI>Settings>Organization Settings> Protect Agent> Install. Copy your Install Key and paste it here.
Select, “Install”
If you’re not currently logged in as an Administrator, you will need Administrator credentials to allow the installation.
Finally, click on “Close” and you’re all set! The HPA is now installed and protecting your machine!
By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is running or not.
Installing the Agent - Silent
A ‘silent’ installation means that the application is installed or deployed without any input or interaction from the end user. To silently install the HPA, please follow the steps below.
Please make sure to follow ALL of the steps listed below BEFORE attempting to execute this command.
This assumes the Agent has already been downloaded to the machine.
If deploying the Agent via a golden image, take note that this can often duplicate machine IDs therefore making it appear as if all machines deployed via the golden image are the same machine int he logs.
Downloading the HYAS SSL Certificate
Due to changes introduced in macOS 15, clients must install the HYAS SSL certificate on their machines to enable a fully silent installation. This only applies to machines that have not installed previous versions of the HYAS Protect Agent.
You can use the following curl command to install the certificate via your preferred deployment method:
curl -sSL https://ca.hyas.com/cert/pem/hyas-protect-ca-cert.pem -o /tmp/hyas-protect-ca-cert.pem
sudo security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain /tmp/hyas-protect-ca-cert.pem
rm -f /tmp/hyas-protect-ca-cert.pem
Installing the Agent
Copy the following curl command
- BASH
client_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" install_dir="$HOME/Downloads" install_file="HYAS-Protect-latest.pkg" echo "${client_id}" > /tmp/.hyas.protect.client.id install_path="${install_dir}/${install_file}" sudo installer -pkg "${install_path}" -target /
Replace the client_id, noted above as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your client ID
To obtain your client_id, navigate to the HYAS Protect UI>Settings>Organization Settings> Protect Agent> Install. Copy the ‘Install Key’, this is your client_id
Once you’ve replaced the client_id as described above, proceed with executing the command.
If the installation does not complete successfully, please make sure you’ve updated the variable in step 2 above.
Starting the Agent UI
By default, the Agent’s UI will not launch upon install however, the HPA service is running and protecting your machine in the background.
The HPA UI provides feedback, status updates and other information related to the HPA. If you wish to start the UI to view these, please perform the following steps:
To start the HPA UI,
Navigate to the Launchpad
Search for and click on HYAS. This will start the UI.
Checking Agent Status
When checking status, keep in mind that the HPA communicates with the HYAS Protect backend approximately every 5 minutes, so statuses may not appear immediately in the HYAS Protect SaaS UI.
HYAS Protect SaaS UI
Administrators may check the status of all HPA’s from the ‘Manage’ tab in the ‘Protect Agent’ section of the HYAS Protect SaaS UI.
Login to HYAS Protect, click on Settings>Organization Settings> Protect Agent> Manage.
From this view, you can check the ‘Status’ column to get information on the status of all the Agents.
HYAS Protect Agent UI
It is also possible to check the status of the HPA on the local machine itself.
By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is open or not.
Ensure the HPA UI is running.
If you do not see the HYAS
in the menu bar, the HPA UI is not running. This does not mean that HYAS Protect is not protecting the machine. This only means the UI is not running.
To start the HPA UI follow the instructions listed above under ‘Starting The Agent UI’
With the UI running, click on the HYAS icon in the menu bar.
You’ll be presented with the following window:
Green means everything has passed checks and is working properly. Red signifies that there is an issue with the status and further troubleshooting may be required.
Agent Status Definitions
Protection Active
This shows the overall status of the Agent.
Internet Check
Checks if the HPA can reach the HYAS resolver directly. The HPA will do a DNS lookup that only HYAS can answer.
Proxy Check
This checks whether the DNS proxy can connect to the HYAS backend. It verifies both if the service running on localhost:53 belongs to HYAS and if it can communicate with HYAS's backend. It performs a lookup that only HYAS can respond to. Therefore, if another DNS proxy is using port 53, this check will not succeed.
OS Check
This asks the OS to do a DNS lookup. If the system is configured to use the HPA, the lookup will go to the DNS proxy and we are at step 2 again. If this fails, some other process has reconfigured DNS and competing with the HPA for DNS resolution.
Agent Preferences
The HPA on the local machine includes configurable preferences to provide greater flexibility, visibility, and advanced troubleshooting. To access Preferences, start by navigating to the Menu Bar and right-clicking the HYAS Protect icon.

Once you click on Preferences, you’ll see the three options below:

Start UI at login
Enabling this will ensure that the GUI is started on machine login.
The HPA will still run in the background - and be protecting your machine - regardless whether the UI is running or not.
Notifications
Turning this on allows the Protect Agent to send you notifications regarding connectivity or errors that may have occurred.
Debug Mode
Toggling this on can be useful if you’re having issues with your Agent. This feature enables additional logs to be collected for Client Admin or HYAS analysis.
Disabling/Enabling the Agent
Disabling
There are a few different options to “Turn off” the Agent. Let’s dive into the differences.
Disabling the UI only
This turns the UI off but allows the HPA to still run in the background.
Click on the HYAS Protect icon in the Menu Bar to access the settings. You’ll see the following popup.

Clicking “Quit” here will turn off the HYAS Protect UI.
The HPA will still run in the background - and be protecting your machine - regardless whether the UI is running or not.
Re-enabling the UI only
If the HYAS icon is missing from the Menu Bar, it means the UI isn’t running.
To start the UI, see instructions above titled, ‘Starting the Agent UI’
Disabling Protection Locally
If you wish to disable the HPA completely, you must stop the service itself.
This will completely stop HYAS Protect from running and it will no longer be protecting your machine.
Click on the HYAS icon in the Menu Bar.
Select, ‘Disable Protection’
This will disable the HPA completely for a period of 5 minutes.
If you are unable to select ‘Disable Protection’, your Administrator must toggle the feature on via the HYAS Agent Central Management Console. Instructions for Admins on completing that here.
Re-enabling Protection Locally
The HPA will automatically restart after 5 minutes. However, if you wish to restart the HPA sooner perform the following:
Navigate to the HYAS Logo in the Menu Bar, click on it and select ‘Enable Protection’

This will re-enable the HPA to begin protecting your device again.
Disabling Protection via the HPA Central Management Console
HYAS Protect Admin privleges are required to manage agents in the Central Agent Management Console.
Navigate to the ‘Manage’ tab of HPA Central Agent Management Console.
Select the Agent(s) you wish to disable by selecting the check box next to the Agent(s) and selecting the ‘Action’ button
at the top of the screen or by selecting the Actions icon
at the right of the page.
Then select ‘Disable Agent'
This will disable the Agent indefinitely. The HPA must be manually re-enabled before it can resume protecting the selected devices.
Confirming the Agent’s Running State
By default, the Agent runs in the background and automatically protects your machine upon installation. However, if you’d like to confirm that it’s running, you can do so by following one of the procedures below:
By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is running or not.
If the UI is NOT running (default state)
Run the Check Running State script in the Terminal.
If the UI is running
Navigate to the Menu Bar at the top of the screen and you should see:
The H with the solid dot signifies that the HPA, (both service and UI is up and running)
Updating the Agent
Like all software, regular updates are crucial for fixing bugs, adding new features, and improving client experience and overall security. The update method for the HPA may differ depending on the version, so please refer to the instructions below for details specific to your version.
Regardless of the update method, HYAS STRONGLY recommends using a phased rollout approach. This involves updating a few machines at a time, testing them, and then proceeding with additional updates. This standard practice for software updates helps ensure easier troubleshooting and minimizes the risk of widespread issues.
Due to system limitations introduced in macOS 15, updating older versions of the HYAS Protect Agent (v2.2.11 and earlier) to v2.2.12 via the web portal (Protect Agent > Manage > Actions > Update Agent (v2.2.7+)) is not currently possible. Updates must be performed manually or through your MDM.
Agent v2.2.7 and Newer
If you machine(s) are currently on HPA v2.2.7 or newer, you may update to newer versions (2.2.8+), directly from the HYAS Protect SaaS UI.
Navigate to HYAS Protect, click on Settings>Organization Settings> Protect Agent> Manage.
Select the machine(s) you which to update (ensuring they are running v2.2.7 or newer)
Click on ‘Action’
Then select ‘Update Agent (v2.2.7)’
Allow up to 15 minutes for the updates to complete.
Agent v2.2.6 and Older
If you have HPA v2.2.6 or older you will not have in-place updating capabilities until you’ve updated to v2.2.7+. This means, you need to manually update your agents.
However, if you are updating to v2.2.5 or newer, it will automatically look for older versions of the HPA dating back to at least 2.1.1 and automatically uninstall the older version as part of the update process.
In all other cases, please manually uninstall the older HPA per the instructions below. For installation, follow the instructions listed above for downloading and installing the HPA.
Uninstalling the Agent
v2.2.6 and Newer
If your machines are running v2.2.6 or later, the easiest way to uninstall the HPA is through the ‘Manage’ tab in the HYAS Protect SaaS UI
Navigate to HYAS Protect>Settings>Organization Settings>Protect Agent>Manage
From the ‘Manage’ tab, select the machines you wish to uninstall the Agent from, click on ‘Action’ and select ‘Uninstall (v2.2.6+)’
After approximately 5 minutes, the HPA will be uninstalled from the desired machines.
v2.2.5 and Older
Older versions of the HPA require a different procedure, although this method will also work on newer versions as well.
Stop the HYAS Protect service.
Navigate here for instructions on stopping the service.
Next, navigate to the Finder
Click on Applications
Search for HYAS Protect
Right-click on HYAS Protect and select, “Move to Trash”.