Android Filtering Mode Guide

Two Modes

The CleanBrowsing Android app supports two filtering modes that control how DNS queries are transported to CleanBrowsing's resolvers. You access the mode selector by tapping the gear icon on the Status screen to open Settings, then tapping Mode.

The Mode screen shows two cards: Private DNS and VPN. The currently active mode has a filled radio button. Tapping the inactive card opens a confirmation dialog, and after you confirm, an interstitial screen appears while the app transitions to the new mode.

Both modes apply your configured filter (Family Filter, Adult Filter, or your custom premium filter) using the same CleanBrowsing resolvers. The difference is only in how DNS queries reach those resolvers — not which filter rules are applied.

Private DNS Mode

Private DNS mode is the default and recommended setting for most users. It uses Android's system-level Private DNS feature, which routes DNS queries over DNS-over-TLS (DoT) on port 853. The app's Accessibility Service configures the Private DNS hostname automatically — you do not need to touch system settings manually.

Active Health Check

While in Private DNS mode, the app runs an active health check every 60 seconds to confirm that port 853 is reachable. The health check works as follows:

1. The app tests CleanBrowsing's DoT resolver on port 853.
2. If the test fails, the app waits 5 seconds and retries once.
3. If the retry also fails, the app cross-checks Cloudflare's DoT resolver (1.1.1.1 on port 853) as a neutral reference point.
4. If both CleanBrowsing and Cloudflare's DoT fail, the app concludes that port 853 is blocked network-wide and posts a notification so you can decide how to proceed.
5. If only CleanBrowsing's DoT fails but Cloudflare's succeeds, the app treats this as a CleanBrowsing-specific issue, remains on Private DNS mode, and logs the result.

When Port 853 Is Blocked — Your Options

When the health check detects a network-wide port 853 block, the app posts a persistent notification: "Port 853 is blocked on this network. Tap to review your options." Tapping the notification opens a screen with three choices. You must select one — the screen cannot be dismissed without choosing.

Allow Network Login — Auto-Resume Detail

When you choose Allow Network Login, the app turns off Private DNS so your device can reach the captive portal login page. Once you authenticate and internet connectivity is confirmed, the app starts a 2-minute timer and then automatically re-enables Private DNS without any further action from you.

During the 2-minute window, the Status screen shows "Filtering Paused" in orange. After Private DNS is restored, the status returns to green.

VPN Mode

VPN Mode routes all DNS queries through a local VPN tunnel on your device using DNS-over-HTTPS (DoH) on port 443. There is no reliance on Private DNS or port 853 in this mode.

How the VPN Works

The VPN is entirely local — it runs on the device itself and only intercepts DNS queries. It does not route your web browsing traffic through a remote server. Your actual HTTP/HTTPS requests go directly from your device to the internet without any VPN routing. Only DNS queries are tunneled.

The DoH tunnel connects to the same CleanBrowsing resolvers used by Private DNS mode, so the same filter rules apply — your custom filter, Family Filter, or Adult Filter behaves identically in both modes.

What You'll See

• A VPN icon (key icon) appears in the Android status bar whenever VPN Mode is active. This is normal — it indicates the local VPN tunnel is running.
• The Status screen shows your filter name in green, confirming filtering is active.
• The health check is disabled in VPN Mode. The app will not periodically re-test Private DNS or switch back automatically. You would need to manually switch back to Private DNS from Settings → Mode if desired.

Battery Impact

VPN Mode uses slightly more battery than Private DNS mode because maintaining the local VPN service requires the OS to keep additional resources active. For most users, the difference is minimal. If battery life is a concern and your network supports port 853, Private DNS mode is the lower-impact option.

Switching to VPN Mode

Follow these steps to switch from Private DNS mode to VPN Mode:

1. From the Status screen, tap the gear icon to open Settings.
2. Tap Mode.
3. Tap the VPN card.
4. A confirmation dialog appears. Tap "Switch to VPN" to proceed.
5. The app triggers the Accessibility Service to remove the Private DNS setting from Android's system settings. This clears the DoT hostname so Android stops using Private DNS.
6. A "Setting up VPN Mode" interstitial screen appears for approximately 1.5 seconds. This pause gives the OS time to fully propagate the Private DNS removal before the VPN tunnel starts — preventing a race condition where both Private DNS and the VPN tunnel could be active at the same time.
7. If this is the first time you are granting VPN permission on this device, Android will display a system permission dialog. Tap OK to allow the VPN connection.
8. The Status screen returns and shows your filter name in green, confirming VPN Mode is active. The VPN key icon appears in the Android status bar.

Switching to Private DNS Mode

Follow these steps to switch from VPN Mode back to Private DNS mode:

1. From the Status screen, tap the gear icon to open Settings.
2. Tap Mode.
3. Tap the Private DNS card.
4. A "Restoring Private DNS" interstitial screen appears for approximately 1.2 seconds. This pause gives the VPN tunnel time to fully stop before the app configures the Private DNS hostname — preventing a situation where both the VPN and Private DNS are briefly active simultaneously.
5. The Accessibility Service opens Android's system settings and sets your filter's DoT hostname in the Private DNS field automatically.
6. The Status screen returns and shows your filter name in green via Private DNS. The VPN key icon disappears from the Android status bar.

After switching to Private DNS mode, the health check resumes immediately. If port 853 is reachable on your current network, filtering continues via Private DNS. If port 853 is blocked, the health check will detect this within 60 seconds and notify you to choose how to respond.

Filter Profile Carries Over

When you switch modes in either direction, your filter profile transfers automatically. You will not need to re-enter your activation code or reconfigure your filter after switching.

The app stores your DNS hostname in a local encrypted cache so it can restore it when switching back to Private DNS mode. The same hostname is also used to construct your DoH endpoint URL for VPN mode. This means:

• If you are using a custom premium filter, your unique DoT/DoH hostname is cached and re-applied in both modes.
• If you are using a free filter (Family or Adult), the shared hostname for that filter is applied in both modes.
• The filter name shown on the Status screen (Family Filter, Adult Filter, Premium Filter) should be the same before and after switching.

Status Screen in Each Mode

The Status screen shows your current filtering state regardless of which mode is active. Here is what you will see in each scenario:

Private DNS Mode (Active)

• Your filter name (e.g., Family Filter, Adult Filter, or Premium Filter) appears in green.
• The filter name is sourced from the active Private DNS hostname that Android reports as currently configured.
• No VPN icon appears in the Android status bar.

VPN Mode (Active)

• Your filter name appears in green.
• The filter name is sourced from the DoH endpoint URL configured inside the VPN tunnel.
• The VPN key icon appears in the Android status bar.

Filtering Paused — Allow Network Login

• The status screen shows "Filtering Paused" in orange.
• No filtering is active — DNS queries go to your network's default resolver.
• The health check runs every 60 seconds. When internet is detected, a 2-minute countdown starts, then Private DNS is automatically re-enabled.

Filtering Disabled (Manual)

• The status screen shows "Filtering Disabled" in red.
• A "Re-enable Filtering" button appears. Tapping it re-enables Private DNS immediately — no password required to re-enable.

Captive Portal (Either Mode)

• The status screen turns orange and shows a captive portal indicator when a Wi-Fi network is detected that requires a login.
• If DoH on port 443 is reachable, filtering continues through the VPN tunnel and an Open Wi-Fi Login button appears.
• If both DoT and DoH are blocked by the captive portal, the status shows Filtering Paused and filtering resumes automatically once you complete the login.

When to Use VPN Mode

For most users, Private DNS mode (the default) is the right choice. The auto-fallback mechanism handles temporary port 853 blocks without any manual intervention. Use the guidance below to decide when to switch to VPN Mode permanently.

Stick with Private DNS (default) if:

• You are on most home, school, or office Wi-Fi networks
• You are on mobile data with a major carrier (most support port 853)
• Filtering is working reliably and you are not seeing frequent auto-fallback events
• You want minimal battery impact

Switch to VPN Mode if:

• Your carrier or network consistently blocks port 853 — for example, some mobile carrier networks silently drop DoT traffic, or corporate firewalls that do not allow outbound port 853
• You frequently receive port-blocked notifications — this indicates a persistent port 853 block on your regular network. Switching to VPN Mode permanently avoids the repeated health check alerts and the notification flow
• You have confirmed via the Diagnostics report that DoT consistently fails while DoH succeeds

How to Confirm Which Mode is Active

Open the app and tap Diagnostics from the Status screen. The Filtering Mode section at the top of the diagnostic report shows whether the app is currently in Private DNS or VPN mode, and whether the VPN tunnel is active. This is the most reliable way to confirm which transport is in use — especially useful after a mode switch or if you are troubleshooting with support.

Android Diagnostics Guide →