In this article

This article outlines how to deploy a Roaming Client on a Windows or macOS device, and includes links to deployment instructions for RMM tools, Entra ID, and PGP/GPG programs. 

Deploying the Roaming Client is an easy solution if your ISP uses Carrier-Grade NAT because the agent bypasses the need for a local device IP address altogether. 

Confirm your OS version aligns with the Roaming Client functionality before attempting to deploy. 

Environment Preparation

Preparing your network environment for deployment can prevent errors, misconfigurations, and internet connectivity issues. Use these articles to set yourself up for success.

• Prep your network for deployment by checking these common settings that can conflict with DNSFilter. 
• Review the Captive Portal article to prevent connectivity issues at locations like airports, hotels, or on public Wi-Fi 
• Set your firewall to not block EDNS to keep local DNS resolution from failing. Here are the Windows and macOS instruction
• Prevent end-users from circumventing filtering policies in the firewall or Roaming Client configuration 
• Consider other settings that can conflict with the agent like VPNs, Security software, and Browser extensions
• mac users disable the Hide IP Address option in the Privacy settings so web pages fully load

Install a Roaming Client

✍️ When attempting to manually update the agent version, remember to uninstall the older version (Windows or macOS instruction) and then complete these steps to install the latest Roaming Client. 

Windows video tutorial

macOS video tutorial

Step one: Create an associated Site

See how Sites and Roaming Clients work together to understand filtering policy and billing details.  

1. Create a new Site (or select an existing Site) to associate with the Roaming Client
2. From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients
3. Tab to Install
4. Select the Site
5. Copy the Site Secret Key

Step two: Download and run the installer

1. From the same page in the DNSFilter dashboard, download the DNSFilter installer from the applicable OS menu
2. Run the installer
   1. Paste in the Site Secret Key
   2. Click through the installer and agree to any security prompts

The Roaming Client is now active and filtering DNS requests. A tray icon will appear and show active status (for Windows users the icon appears green or blue).  See our macOS or Windows Roaming Client troubleshooting articles if the tray icon shows an error (icon appears red or offline). 

It's not currently possible to hide the tray icon for the macOS Roaming Client. If this is a feature you are interested in, vote to express your interest and be notified of any development on this request.

Step three: Test the connection

1. Verify the Roaming Client is active and filtering the desired categories by visiting debug.dnsfilter.com
2. Attempt to browse to a well-known domain that is allowed by your policy (i.e., google.com)
3. Attempt to visit a domain on your policy Block List in Incognito Mode

When deploying the agent to a team, DNSFilter recommends testing the policy with a small, mixed group of users (e.g. users from different departments, permission levels, or experience) to fine tune settings. Test for 1-2 days with multiple devices to ensure smooth operation before performing a mass deployment.

Add Local Domains (optional)

Adding Local Domains sends DNS queries to the local DNS resolver instead of DNSFilter. Completing this step is useful for corporate networks with some 'source of truth' for Split-Horizon DNS, e.g. LAN-only domains or local IPs returned for corporate resources.

Learn more about how and why to utilize Local Domains with your DNSFilter configuration to determine if these steps are necessary for your situation. Follow in-app instruction to add Local Domains and Resolvers.

Enable DNS-over-TLS (optional)

To prevent DNS interception or tampering by third parties, you may optionally configure the Roaming Client to use DNS-over-TLS. The article Enabling DNS-over-TLS explains how to enable on Roaming Clients.

Related deployment articles

Deploy the agent via Silent Install, Entra ID (formerly Active Directory), RMM tool, or add an extra layer of protection with PGP/GPG programs.

Learn more about Roaming Clients

• See our deployment options guide for a high-level overview of Roaming Clients
• Explore the technical details of Roaming Client components, proxies, and start up: all the ins and outs of how Roaming Clients work!
• Set yourself up for success by learning how to manage Roaming Clients from the DNSFilter dashboard
• Follow Roaming Client releases to stay up to date on our release notifications
• Use the uninstall guides to remove the Roaming Client from Windows or macOS devices individually or with RMM tools