In this article

DNSFilter account users with admin permissions or higher use this article to uninstall the macOS Roaming Client on individual devices, or remotely using a mobile device management (MDM) tool.

Beginning with v2.2.0, remote (silent) installs of the macOS Roaming Client include three .mobileconfig profiles that must be uninstalled alongside the agent package.

⚠️ Important: Deleting the agent from the DNSFilter dashboard does not uninstall the Roaming Client. Deleted agents reappear in the dashboard on the next sync.

Standard uninstall (run on end-user device)

Run this command from the device terminal:

• sudo sh "/Applications/DNSFilter Agent.app/Contents/Resources/uninstall.sh"

• sudo sh "/Applications/DNS Agent.app/Contents/Resources/uninstall.sh"

The uninstall script prompts whether to remove the configuration and registration files (configuration.json, daemon.reg, registration.json, and related files under /Library/Application Support/). The default keeps these files. The -kc (keep config) flag controls this behavior and can be set explicitly to avoid the prompt:

To set the flag explicitly, add -kc yes or -kc no to the full command:

• Keep configuration:

  sh "/Applications/DNSFilter Agent.app/Contents/Resources/uninstall.sh" -kc yes

  Remove configuration:

  sudo sh "/Applications/DNSFilter Agent.app/Contents/Resources/uninstall.sh" -kc no

• Keep configuration:

  sh "/Applications/DNS Agent.app/Contents/Resources/uninstall.sh" -kc yes

  Remove configuration:

  sudo sh "/Applications/DNS Agent.app/Contents/Resources/uninstall.sh" -kc no

For MDM or scripted deployments, always set -kc explicitly rather than relying on the interactive prompt.

✍️ Reinstalling on the same device: To uninstall and then perform a clean reinstall, use -kc yes to preserve the Site binding. The reinstalled agent reconnects to the same DNSFilter Site without counting as a new device registration.

✍️ Dashboard cleanup: Running the uninstall script automatically removes the agent from the DNSFilter Roaming Clients dashboard, so no manual cleanup is required. If the device is offline when uninstalled, it may remain listed as offline. From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients, then delete the device manually in that case.

Silent uninstall (run via MDM tool)

As with installation, the Roaming Client can be uninstalled remotely with an MDM tool using the commands above. DNSFilter does not endorse or validate third-party software processes. For MDM-specific steps, consult the vendor's documentation.

v2.2.0+ (System Extension agent)

Uninstalling the v2.2.0+ agent includes removing the .mobileconfig profiles pushed during deployment.

1. Uninstall the agent installer package using the commands above
2. Following the MDM's processes, remove the .mobileconfig profiles in this order:
   1. Proxy.mobileconfig
   2. Extension.mobileconfig
   3. Combined_Certificates.mobileconfig

✍️ Some MDM tools may display the certificate profile under its older name, DNSFilter_Certificates.mobileconfig.

⚠️ MDM-managed profiles: Profiles deployed with user removal disabled (PayloadRemovalDisallowed: true) cannot be removed by a script running on the device. Removal must be pushed from the MDM's profile management interface. If the device is no longer enrolled, or MDM access is unavailable, use Apple Configurator 2 to remove the profiles directly. In environments where the MDM profile prevents the uninstall script from removing the system extension or disabling the DNS proxy, remove the MDM profile from the MDM console before running the uninstall script.

v1.8.6 and older (Legacy agent)

The v1.8.6 and older agent does not deploy .mobileconfig profiles, so there are none to remove. Run the uninstall script only, using the commands above.

Verify the uninstall

Confirm the agent and its network proxy are fully removed:

• In macOS System Settings, open Network and confirm the DNSFilter DNS proxy no longer appears under Network Filters
• From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients, then confirm the device no longer appears or shows as deleted
• Optionally, run dig debug.dnsfilter.com txt; queries resolve through the device's default system DNS rather than DNSFilter once the agent is removed

These checks confirm the macOS Roaming Client is uninstalled and no longer receiving DNS traffic.

DNS filtering continues after the uninstall

If the checks above show the DNS proxy still present, or dig debug.dnsfilter.com txt still returns a DNSFilter response after the uninstall and a restart, the system extension is still active. This happens when the administrator authorization prompt for removing the extension was not answered (for example, during an MDM-run uninstall, where nothing is able to answer it). The agent and its files are removed, but the extension remains and re-activates on every restart.

To confirm, run systemextensionsctl list. A stuck extension appears as [activated enabled] while no DNSFilter application is present on the device.

To resolve a stuck DNS proxy extension:

1. In your MDM, unassign the Extension configuration profile from the device
   ✍️ The Extension profile is separate from the Proxy profile. Both need to be unassigned. 

2. Wait approximately 15 seconds for the extension to move to a terminated state 

3. Restart the device

4. Repeat the checks above and confirm the DNS proxy is gone and DNS resolution no longer goes through DNSFilter

Unassigning the Extension configuration profile is the only action that ends this state. It cannot be done from the device: a script running on the device cannot remove an MDM-managed profile, and the filter toggle in System Settings is unavailable while the Proxy profile is assigned. If the device is no longer enrolled in an MDM, use Apple Configurator 2 to remove the profiles directly.

Related content

• Install the v2.2.0+ agent with an MDM solution or manually
• Troubleshoot end-user prompts still occurring with the v2.2.0+ build deployed via MDM
• End-users report lost internet connectivity after the agent update
• The network environment runs another DNS proxy such as an EDR or VPN, and macOS allows only one proxying agent per device