System requirements: **macOS Tahoe 26** or later, Mac with **Apple silicon — M1 chip** or later. The Agent is available on the following billing plans: **Safe Family, Pro, Pro Plus,** and archived **Safe@Home, Safe@Office**.
#### This guide explains how to deploy **SafeDNS Endpoint Lite for macOS** to multiple macOS devices using an MDM solution. ##### **The deployment consists of three components:** - A **merged configuration profile** (system extension approval + DNS Proxy), deployed through MDM as a single `.mobileconfig` file: [**SafeDNS\_merged\_profile.mobileconfig**](https://docs.safedns.com/attachments/19)**.** - The **config.plist** file, created on the target devices by the **[SafeDNS\_Installer.sh](https://docs.safedns.com/attachments/21)** script. The administrator needs to add the **AuthKey** into the script. - A **single installer package** that contains the daemon, the host, and the filtering module: **[SafeDNS Endpoint Lite\_1.8.0.0\_2026-09-15\_1215.pkg](https://docs.safedns.com/attachments/23).**The order in which these three components are assigned does not matter, but we recommend deploying the **config.plist** and the **configuration profile** first. The package has a built-in safeguard (config gate): if it reaches a device before the script that creates config.plist, it waits up to 5 minutes for **config.plist** to appear, and only then installs the daemon, registers the device, and deploys the host.
#### **1. Installing the agent** ##### Before deploying the agent at scale, complete the preparation steps below. - Ask SafeDNS technical support (support@safedns.com) to enable the required features for your account. - Obtain your **Base64-encoded AuthKey** from SafeDNS. After these steps are complete, assign the three objects below to a device group in your MDM solution. They can be assigned in any order. ##### **Step 1. Merged configuration profile** Upload and assign **one** profile. It contains two payloads: - **System Extension approval** (`com.apple.system-extension-policy`) — silently approves the SafeDNS system extension. - **DNS Proxy** (`com.apple.dnsProxy.managed`) — activates the DNS proxy without prompting the user. File: **[⤵SafeDNS\_merged\_profile.mobileconfig](https://docs.safedns.com/attachments/19).** Upload it as a **Custom Configuration Profile** (device profile). ##### **Step 2. config.plist (the AuthKey needs to be added by the administrator)** Upload and assign the configuration script according to **[these instructions](https://docs.safedns.com/books/installation-guides/page/creating-the-configplist-file-for-safedns-endpoint-lite-on-macos)**. **You enter the key into the script yourself.** This is a security requirement: the key is never embedded in the installer package. ```bash AUTH_KEY="Enter here your authKey " # ← enter your Base64-encoded AuthKey here ``` The script creates the `/Library/Application Support/SafeDNS/config.plist` file with the `AuthKeyBase64` key. ##### **Step 3. Single installer package (daemon + host + filtering module)** Upload the **[SafeDNS Endpoint Lite\_1.8.0.0\_2026-09-15\_1215.pkg](https://docs.safedns.com/attachments/23)** file to the **Apps** catalog of your MDM solution and assign it to the same device group. The package performs the following steps automatically and in the correct order: 1. The daemon is installed and started, and it registers the device in the SafeDNS Dashboard. 2. The registration is verified (`dnsToken`). The host is deployed **only after** successful registration. 3. The host with the filtering module is moved to `/Applications`, and the system extension is activated silently (using the profile from Step 1). To verify the installation, run the following commands on a target device: ```bash # The SafeDNS extension must be listed as [activated enabled] systemextensionsctl list # Prints the dnsToken if the device is registered /usr/libexec/PlistBuddy -c "Print :dnsToken" "/Library/Application Support/SafeDNS/state.plist" ```The agent runs in the background and has no user interface.
#### **2. Uninstalling the agent** ##### To remove SafeDNS Endpoint Lite from target devices: 1. Add the **SafeDNS\_Uninstaller.sh** script to **Scripts** in SimpleMDM according to the **[Running the SafeDNS Uninstaller script](https://docs.safedns.com/books/installation-guides/page/running-the-safedns-uninstaller-script)** guide. 2. Deploy the uninstaller script to the target devices. 3. Remove the **SafeDNS configuration profile,** the **SafeDNS Endpoint Lite** agent and **SafeDNSDaemon** daemon from the target devices in your MDM console. 4. After the uninstaller script runs, each target device **restarts automatically after 3 minutes**.**IMPORTANT!** After the agent and the daemon are removed, each target device must be **RESTARTED**. The restart happens automatically 3 minutes after the uninstaller script runs. The agent runs as a system extension. After removal, its records remain in the system extension registry until the device is restarted. Without a restart, reinstalling the agent on the same device may cause errors.
#### **3. Choosing the DNS transport protocol** The administrator sets the DNS transport mode using the **[Switch\_mode.sh](https://docs.safedns.com/attachments/25)** script, which must be deployed to the target devices in advance. Available modes: - `UDP` — DNS over UDP (port 1253) - `DoH` — DNS over HTTPS (port 443) - `DoT` — DNS over TLS (port 853) #### **4. Preventing DoH bypass in browsers** Advanced users **may try to bypass** system DNS filtering by configuring a custom DNS-over-HTTPS (DoH) resolver in Chromium-based browsers. The SafeDNS agent works with system DNS, so additional protection is required to reduce this risk.SafeDNS provides two layers of protection against this scenario:
##### 1. Browser DNS policy configuration profile Download and deploy this custom configuration profile: **[⤵safedns\_browser\_dns\_policy.mobileconfig](https://docs.safedns.com/attachments/26)** This profile is deployed in the same way as the merged configuration profile from Step 1. The profile restricts access to DNS-related settings in major browsers. However, it does not cover all browsers: **Firefox is not included**. ##### 2. Built-in DoH bypass detection The SafeDNS filtering module includes a mechanism that detects attempts to bypass filtering through third-party DoH services and blocks those connections. It blocks the bootstrap domains of public DoH providers (Cloudflare, Google, Quad9, and others).If an advanced user manually configures a **self-hosted DoH resolver** or another non-standard **custom DoH solution** in the browser, DNS filtering may not work as expected.
#### **5. VPN limitation — important notice****IMPORTANT:** A VPN that resolves DNS remotely bypasses the agent's filtering.
The agent filters traffic at the DNS resolver level: it intercepts queries sent to the system DNS. A VPN that resolves domain names **on its own server** (remote DNS) takes those queries out of the agent's sight, so filtering does not work for that traffic. This is **not a defect of the agent**. It is a fundamental limitation of DNS-level filtering on macOS, and every product that filters at the DNS level behaves the same way (e.g. DNSFilter, NextDNS, Cisco Umbrella). Examples of VPNs with remote DNS: - **Browser VPN extensions** (HTTP/SOCKS proxies): SandVPN, Browsec, Hola, Urban VPN, Touch VPN, ZenMate, and similar. - **VPN clients** (DNS leak protection is enabled by default): NordVPN, ExpressVPN, Surfshark, Proton VPN, Private Internet Access, IPVanish, CyberGhost, Mullvad, IVPN, Windscribe, and similar. - **WireGuard / OpenVPN** — if the tunnel configuration overrides the DNS server with the VPN server (standard for commercial providers). ##### **Ways to address this limitation**| Option | What it does | Best for |
|---|---|---|
| **Split-tunnel VPN** (recommended) | The VPN tunnels only corporate routes. All other traffic, including DNS, goes through the system resolver, so filtering works. | Customers who need a VPN to access internal resources |
| **Blocking the Proxies & Anonymizers category** | The DNS filter blocks the domains of VPN providers, so the VPN client cannot connect. | Customers who do not need a VPN for work |
| **Allowlist** | The domain of the legitimate corporate VPN is added to the SafeDNS Allowlist. It resolves, while everything else stays blocked. | Used together with blocking the Proxies & Anonymizers category |
| **Blocking VPNs at the MDM level** | An MDM policy prevents users from installing or running VPN clients and browser extensions. | Corporate devices with a strict policy |