Skip to main content

Deploying to Mac

As a browser-based platform, Keep Aware is highly compatible with the macOS operating system. For browser compatibility notes, see Specifications & Constraints.

Getting started​

Before you begin, make sure you have access to an administrative or MDM platform such as Jamf, Intune, or Kandji. The most common method for macOS deployments, is a combination of a package-based installer and an MDM configuration profile. For manual installs, you’ll need a company email.

Finally, find your Keep Aware tenant key (ka_host) and start key (ka_start) by opening the Settings page, and selecting View tenant details for your organization.

Mac deployment​

Keep Aware can be quietly installed on macOS devices through a package file. The installer initiates the Keep Aware client which periodically checks for available browsers on the device and coordinates the installation of the Keep Aware browser extension. For more information on Safari specifically, refer to Managed Safari settings below.

Once downloaded, unzip the installer and deploy with the following command, or through the installer capability in your MDM platform.

After installing the package, the installation action can be invoked by running the following script or command:

Post-installation command​

Command-line parameters

Mandatory Parameters

  • --KA_HOST (string) => This value is available in the settings section of the console
  • --KA_START (string) => This value is available in the settings section of the console
  • --KA_NAME (string) => This is the name of your organization. e.g. Example, Inc.

Optional Installer Flags These flags must be given a 1 or a 0 as values. A 1 will enable this feature, a 0 will disable it, descriptions and defaults listed below:

  • --INSTALL_EXTENSION (Default: enabled) => Install the browser extension on all supported browsers on the local device
  • --INSTALL_POLICY (Default: enabled) => Install policy keys to each supported browser on the local device
  • --INSTALL_NATIVE_MESSAGING (Default: enabled) => Setup native device communication between the browser and the host device
  • --INSTALL_SCHEDULED_TASK (Default: enabled) => Setup a periodic background task to ensure local device data is kept up to date in the Keep Aware Console
  • --INSTALL_BROWSER_POLICY (Default: enabled) => Install browser-specific policy files to managed browsers
  • --SELF_HOSTED (Default: disabled) => Install the browser extension on Chromium-based browsers from the Keep Aware self-hosted repository instead of the Chrome Web Store
  • --EDGE_HOSTED (Default: disabled) => Install the Edge browser extension from the Microsoft Edge Add-ons Store instead of the Chrome Web Store
  • --FIREFOX_HOSTED (Default: enabled) => Install the Firefox browser extension from the Mozilla Add-ons Store
  • --USE_CUSTOM_POLICIES (Default: disabled) => Enable custom browser policies from policies.json
  • --ANTI_TAMPER_POLICIES (Default: disabled) => Enable anti-tamper policies to detect policy modification
  • --DISABLE_UPDATES (Default: enabled — updates are disabled) => Disable automatic client updates
  • --DISABLE_DEVICE_REPORTING (Default: disabled) => Disable device reporting to the console

Optional String Parameters

  • --INCLUDE_BROWSERS (Default: none — all browsers) => Comma-separated list of browser short names to exclusively install on (e.g., chrome,edge,brave). If set, only these browsers are targeted.
  • --EXCLUDE_BROWSERS (Default: none) => Comma-separated list of browser short names to skip. If set, all browsers except these are targeted.
  • --UPDATE_VERSION_DELAY (Default: 0) => Version delay for updates: 0=latest, 1=N-1, 2=N-2
  • --LOG_LEVEL (Default: info) => Set log level: debug, info, warn, error
Alternative: Installing from a single script

Alternatively, a clean installation of the Keep Aware client can be installed by running the following shell script. This will pull the macOS release and install it with your tenant parameters on the device.

Command line​

Core components​

Each deployment method involves the following core components:

  • Keep Aware browser extension: Chrome, Edge, Firefox, Brave and other browsers.
  • Keep Aware client: Typically installed through an installer or package, the client allows information to be synced across browsers on the same device.
  • Managed policy keys: Install keys, the Keep Aware tenant key, and the Keep Aware start key help initialize a browser's connection to a Keep Aware tenant and force-install the extension across web browsers.

Verifying the deployment​

Once deployed, devices should near immediately check in to the Devices page in the console. As browser policy is synced browsers will appear online in the Browsers page. While not required in most cases, restarting the browser will force a policy refresh.

Deploying with existing browser policy​

Keep Aware automatically respects your existing browser policies. When deployed, it safely adds or removes its own settings without disrupting configurations in Chrome, Edge, Firefox, or other browsers.

tip

For production deployments, we recommend consolidating your browser policies and adding Keep Aware settings alongside your existing configurations. Learn more

Enforcing the extension through MDM​

With the client installed, a production deployment can still layer Keep Aware extension alongside your existing browser policies.

In some environments, you may choose to deploy Keep Aware as an extension only. Most core features run through the extension, while installing the full client adds deeper capabilities such as local device enrichment, posture reporting, file hashing on uploads and downloads, and stronger anti-tampering protection.

View guidance for various MDM platforms below:

Managed policy keys​

Keep Aware makes modifications to policy keys through the installer. If browsers are already being managed through configuration profiles, it is best practice to keep those policies in one place. Keep Aware's extension IDs can be found below:

  • Chrome, Edge, Brave and other Chromium-based browsers: camnmdjjfkcplbdlofbndmkmnfeegjoi
  • Firefox: {f61bd1c4-311f-43c3-913f-13b7b37dc144}
  • Safari: com.keepaware.macos.safari (6ALP76LCQK)

Alternatively, to ensure a forced installation of Keep Aware on managed devices, the following configuration profile template can be used by following the steps below:

  1. Configuration Policy: Create a configuration policy or profile for Keep Aware in your MDM.

  2. Import Template (plist or xml): Import the following configuration template. Replace every instance of {{ka_host}} or {{ka_start}} with your tenant key and start key.

    📁 Download Template: Keep Aware macOS MDM Template

  3. Distribution: Apply your new configuration policy to users or groups that you wish to deploy to.

Uninstalling Keep Aware​

If you need to remove Keep Aware from macOS devices, you can uninstall it using the same deployment tools used for installation.

Run the client's uninstall command to remove the browser policy keys, the extension, native messaging registration, and the background daemon:

sudo /usr/local/keepaware/keepaware uninstall
Uninstall parameters

All flags take a 1 or 0. A 1 removes the component, a 0 leaves it in place. Use these when you want a partial uninstall — for example, removing the client while leaving browser policy keys managed by your MDM.

  • --INSTALL_EXTENSION (Default: enabled) => Remove the browser extension from all supported browsers
  • --INSTALL_POLICY (Default: enabled) => Remove policy keys from each supported browser
  • --INSTALL_NATIVE_MESSAGING (Default: enabled) => Remove native device communication between the browser and the host device
  • --INSTALL_SCHEDULED_TASK (Default: enabled) => Remove the background daemon that keeps device data up to date
  • --KEEP_UNINSTALL_LOGS (Default: disabled) => Keep output.log on the device after uninstalling

Removing all client files​

The uninstall command leaves the client binary, configuration, and logs on the device. To remove everything, run the following script. Deploy it through your MDM as a script payload, or run it directly on the device:

#!/bin/bash
set -e

SYSTEM_LOG_DIR="/Library/Application Support/Keep Aware"
LAUNCHD_PLIST="/Library/LaunchDaemons/com.keepaware.client.plist"
CORE_DIR="/usr/local/keepaware"
BIN_PATH="/usr/local/keepaware/keepaware"
CONFIG="/etc/keepaware.conf"

if [ "$(id -u)" = "0" ]; then
    SUDO=''
else
    SUDO='sudo -E'
fi

# Remove policy keys, extension, and native messaging placed by the client
if [ -x "$BIN_PATH" ]; then
    echo "* Uninstalling keys placed by the client..."
    $SUDO "$BIN_PATH" uninstall
else
    echo "* Client binary not found, skipping key removal."
fi

# Remove application files and system-wide logs
echo "* Removing client files..."
$SUDO rm -rf "$SYSTEM_LOG_DIR"
$SUDO rm -rf "$CORE_DIR"
$SUDO rm -f "$LAUNCHD_PLIST"
$SUDO rm -f "$BIN_PATH"
$SUDO rm -f "$CONFIG"

# Remove per-user logs
for user in /Users/*; do
    if [ -d "$user$SYSTEM_LOG_DIR" ]; then
        echo "Removing logs for user $user"
        $SUDO rm -rf "$user/Library/Application Support/Keep Aware"
    fi
done

# Forget the installer receipt
PACKAGE_ID="com.keepaware.client"
if $SUDO pkgutil --pkg-info "${PACKAGE_ID}" >/dev/null 2>&1; then
    echo "* Removing package receipt..."
    $SUDO pkgutil --forget "${PACKAGE_ID}" >/dev/null
fi

echo "* Completed client removal."
note

Run the uninstall command before deleting the client files. Once the binary is removed, the client can no longer clean up the browser policy keys it installed, and they must be removed manually.

After uninstallation, devices and browsers will be marked as uninstalled on the Devices page. Uninstalled devices older than 90 days will be removed automatically.

Table of Contents