Boundary
Client Agent software conflicts
Some software is known to cause conflicts with the Boundary Client Agent. Refer to the transparent sessions interoperability matrix for a list of the third-party products that have been tested for use with the Boundary Client Agent.
The following sections are an incomplete list of potential conflicts and any available workarounds for issues.
Cloudflare WARP client
The Cloudflare WARP client uses a local DNS server to direct traffic. It has built-in checks to prevent it from being run alongside other software that uses the same mechanism. This includes the Boundary Client Agent. If you try to use the Client Agent with the Cloudflare WARP client, it may work, or you may see an error like this one:
Status: Unable to Connect
Error reason: DNS Proxy Failure
Error code: CF_DNS_PROXY_FAILURE
Error description: The WARP Agent must be the only process responsible for DNS resolution on the device. One or more processes are already bound to port 53: boundary-client-agent.
Learn more: https://cfl.re/CF_DNS_PROXY_FAILURE
You can still install both the Cloudflare WARP client and the Boundary Client Agent on the same machine. The two products can coexist as long as the WARP client starts first. Starting the WARP client first binds it to alternate IPs and leaves the domain available for Boundary.
Docker Desktop (MacOS)
Docker Desktop sometimes creates a local DNS listener that prevents the Client Agent from running.
If you run Docker Desktop 4.26 or later, you must clear the Use kernel networking for UDP option.
Otherwise, the Client Agent refuses to start.
Huntress EDR client (Windows)
Host isolation and release do not work as expected in Windows when you use the Huntress EDR client with the Boundary Client Agent. The Huntress EDR client for Windows uses the Windows Filtering Platform (WFP) to isolate devices by blocking all non-essential traffic. This behavior conflicts with the Boundary Client Agent during device isolation. Specifically, the Boundary Client Agent replaces the default DNS resolver with its own, which can prevent fallback to a secondary DNS when the primary (Boundary) DNS fails during isolation. As a result, Huntress is unable to maintain server communication, leaving the device stuck in an isolated state. Huntress cannot isolate and release devices properly in Windows under these conditions.
As a temporary workaround, you can manually configure a secondary DNS (e.g., 8.8.8.8). However, this secondary DNS setting is overwritten when you pause or resume the Boundary Client Agent, so you must configure it again each time.
This issue does not affect macOS devices, where Boundary and Huntress coexist without additional configuration.
Internet Sharing (MacOS)
Enabling Internet Sharing on MacOS causes the system's DNS resolver (mDNSResponder) to bind to all interfaces on port 53, preventing the Client Agent from starting. Disable Internet Sharing before you run the Client Agent.
OpenVPN
When you run OpenVPN at the same time as the Client Agent, it can create a DNS conflict. If you are unable to establish a transparent session while using OpenVPN, you may need to explicitly specify a network interface and upstream DNS server(s) to use.
To configure the DNS server(s) to use, use the override_upstream_dns_servers configuration option:
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
Note
The override_upstream_dns_servers is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
If you configured OpenVPN to push DNS servers to the client, it may create additional conflicts. Refer to the sections below for more information about how this configuration affects MacOS and Windows systems.
MacOS
When OpenVPN is configured to push DNS servers to the client, the client-side service monitors and updates the system DNS settings. As a result, OpenVPN may attempt to override the Client Agent's configuration. This scenario can create an unstable network environment and lead to disruptions in user connectivity and service access. There is no workaround for this scenario at this time.
Windows
When OpenVPN is configured to push DNS servers to the client, it creates DNSClientNrptRule entries in Windows that control DNS routing independently of the interface priority.
Although the Client Agent updates the interface's DNS settings, it does not manage the Name Resolution Policy Table (NRPT).
As a result, the OpenVPN rules may override the Client Agent's configuration.
This scenario may lead to conflicts, and there is no supported workaround at this time.
Palo Alto Networking Global Protect VPN
If you are unable to establish a transparent session while using the Palo Alto Networking Global Protect VPN, you may need to explicitly specify a network interface and the upstream DNS server(s) to use.
By default, the Client Agent reads the primary network interface's DNS server configuration and uses that information to resolve domains that are not configured as aliases in Boundary. If the VPN configuration includes custom DNS servers, this information may not be available to the Client Agent, so you must explicitly specify the DNS server(s) to use.
To configure the DNS server(s) to use, use the override_upstream_dns_servers configuration option:
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
Note
The override_upstream_dns_servers is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
Primary network interfaces
By default, the Client Agent creates IPs on the primary network interface to serve its DNS server. Refer to the tabs below for possible conflicts for each supported operating system.
When you run the Client Agent alongside the PAN-GP VPN, the primary network interface will likely be set to a tun type interface, which the Client Agent cannot use for its IP addresses.
You may see errors such as the following in the boundary-client-agent.log file or the boundary client-agent status command response:
[ERROR] macos.addIP: error adding ipv4 address: ifconfig: ioctl (SIOCAIFADDR): Destination address required
To work around the default tun interface, you must provide an explicit network interface using the interface_to_use configuration option. For example:
interface_to_use=en0
The interface_to_use option allows the Client Agent to create the IPs it needs to serve the DNS server and proxy traffic.
You must restart the Client Agent for it to update its configuration with the new setting.
Parallels Desktop (MacOS VM on MacOS Host)
Running a MacOS VM in Parallels Desktop with shared networking causes the system's DNS resolver (mDNSResponder) to bind to all interfaces, blocking port 53 and preventing the Client Agent from starting.
As a workaround, you can configure Parallels Desktop to use a different network mode. Select an alternative network configuration such as Host-Only, Default Adapter, or Wi-Fi instead of Shared Network. Refer to the Parallels Desktop documentation for more information.
Cisco AnyConnect VPN
When the Cisco AnyConnect VPN is active at the same time as the Boundary Client Agent, DNS resolution may fail for Boundary aliases.
The Boundary Client Agent by default uses the IPv4 range 100.x.x.x for its local proxies. The Cisco AnyConnect VPN treats this range as a secured range, which forces DNS queries to resolve through the VPN instead of the Boundary Client Agent. As a result, Boundary aliases cannot be resolved.
You can configure the Boundary Client Agent to use a different IPv4 prefix by setting the v4_prefix option in the client configuration file. This setting overrides the default 100.x.x.x range and avoids the conflict with Cisco AnyConnect VPN.
For example:
v4_prefix = "172.16.0.0/12"
Note
You can set the v4_prefix to any valid RFC1918 private IPv4 range, as long as it does not overlap with ranges secured by the VPN. Common options include:
Choose a range that best fits your environment.
Uninstall the Client Agent on Mac
If you used the Mac installer, you can run /Library/Application Support/HashiCorp/Boundary Uninstaller.app to uninstall Boundary.
The uninstaller removes any installed components, including the Desktop client, CLI, and the Boundary Client Agent.