Apps that ignore the proxy

Some Mac apps never use the macOS proxy settings, so their requests don’t show up even while Cloak Proxy captures macOS traffic. Typical examples are apps with their own network stack (gRPC, Network.framework) and apps that embed payment or security SDKs. Cloak Proxy spots these apps, lists them under Not Using the Proxy, and can capture them by answering the DNS lookups for their domains and taking the connections itself.

Find apps that skip the proxy

While macOS capture is on, Cloak Proxy checks every 8 seconds for apps with direct connections to the internet. An app appears in the sidebar under Not Using the Proxy when it shows up in two checks in a row, so a connection opened just before capture started doesn’t make it flicker in.

12

CountryDelight connects straight to the internet, so it's listed under Not Using the Proxy.

1. The app and how many direct connections it has open
2. Orange: not captured yet. Click the row to capture it

×

A direct connection is an established TCP connection to a public IPv4 address on port 80, 443, 8080 or 8443 that doesn’t go through Cloak Proxy. Cloak Proxy only lists apps with an app bundle (not system daemons), and never lists itself. Connections to your local network and to localhost don’t count.

Row	Meaning
Orange icon, N direct connections	The app connects straight to the internet. Hover the row to read why its requests don’t show up. Click it to capture it.
Green check, Captured · followed by domains	Lookups for these domains go to Cloak Proxy. Click the row to change the capture.

The section appears only when there’s an app to show. Click its header to collapse it.

Note

Detection only runs while the macOS proxy points at Cloak Proxy. Capturing itself doesn’t need macOS capture: once you’ve captured an app, it’s captured whenever Cloak Proxy is running.

Capture an app

1. Open the capture sheet in one of these ways:

   • Click the app under Not Using the Proxy.
   • Right-click the app under Apps and choose Capture Requests That Skip the Proxy….
   • Press ⇧ ⌘ A and choose Capture followed by the app’s name and (Not Using the Proxy). Search Everything offers this for the first app in the list.

2. Under Domains to capture, check the domains the app uses. Cloak Proxy suggests domains and checks the ones that look like the app’s own.

3. To add a domain that isn’t listed, type it in Add a domain, e.g. api.example.com and press Return or click Add. It’s added at the top, checked.

4. Click Capture. macOS asks for your password to add the resolver files.

5. When the sheet reads Done. Quit and reopen the app so it looks up its servers again; its requests then show up here, click Close, then quit and reopen the app.

The app’s requests now appear in the traffic list. Captured domains are always decrypted, so you see the requests inside, as long as the app trusts the Cloak Proxy root certificate.

1234

The capture sheet suggests the app's domains and checks the ones that match its name.

1. Check the domains to capture
2. Add a domain that isn't listed
3. Notes on scope, password, the background helper and pinning
4. Capture (Update when you edit an existing capture)

×

The capture sheet

Part	What it does
Title and subtitle	Capture the app for a new capture, or the app’s name followed by Capture when you edit one. The subtitle says how many servers it connects to directly, or that lookups for the listed domains are answered by Cloak Proxy.
Domains to capture	One checkbox per domain. When nothing is found, it reads No domains found in the app. Add the ones it uses below.
Add a domain, e.g. api.example.com and Add	Adds a domain. Cloak Proxy removes any scheme, path, port and leading *. or ., so pasting https://api.example.com:443/v1 adds api.example.com. Add stays dimmed until the text is a valid domain. Adding a listed domain checks it.
Notes	Applies to every app on this Mac that uses these domains (and their subdomains). / macOS asks for your password to add a file per domain in /etc/resolver. Stop capturing to remove them. / While Cloak Proxy is closed a small background helper answers these lookups normally, so the app keeps working. / Apps that pin certificates can’t be decrypted; Cloak Proxy then passes them through and still lists the connections.
Pinned (passed through):	Appears in orange when hosts in the checked domains have pinned their certificates. See Pinned apps.
Stop Capturing	Removes this capture. Only shown when you edit an existing capture.
Cancel / Close	Closes the sheet without changes, or after a capture is done.
Capture / Update	Saves the checked domains. Dimmed until at least one domain is checked.

Suggested domains

Cloak Proxy builds the list from two sources:

• hosts the app already reached through Cloak Proxy, and
• host names found in the app’s executable.

It reduces each host to its registrable domain (api.eu.example.co.in becomes example.co.in) and sorts them by how often they appear. Domains that share a word with the app’s name or bundle identifier come first and are checked for a new capture. Up to 25 others follow, unchecked: these are often analytics, payment or other third-party services. Domains that many apps share, such as apple.com, icloud.com, google.com, googleapis.com, gstatic.com, facebook.com, amazonaws.com, cloudfront.net, firebaseio.com and crashlytics.com, are never suggested.

Capture only the app's own domains

A capture applies to every app on your Mac that looks up those domains, including their subdomains. Capturing a domain your browser or other apps also use sends their traffic through Cloak Proxy too, and decrypts it. Check only the domains you need, and avoid shared services.

Change or stop a capture

1. Click the app under Not Using the Proxy (it shows a green check), or right-click it under Apps and choose Edit Capture….

2. Check or uncheck domains and click Update, or click Stop Capturing to remove the capture.

3. Enter your password when macOS asks.

Stopping removes the app’s resolver files. When no captures are left, Cloak Proxy also removes the background helper. Quit and reopen the app so it looks up its servers again and goes back to connecting directly.

There’s no pause switch for a capture. To stop capturing for a while, use Stop Capturing, and capture the app again later: the sheet suggests the same domains.

How DNS capture works

1. For each captured domain, Cloak Proxy writes a file named after the domain to /etc/resolver, for example /etc/resolver/example.com. It tells macOS to send lookups for that domain and its subdomains to 127.0.0.1 port 53535:

   /etc/resolver/example.com

   # Cloak Proxy capture (remove it with Cloak Proxy, or delete this file)
   nameserver 127.0.0.1
   port 53535

   Then it flushes the macOS DNS cache. Resolver files from other tools are left alone.

2. Cloak Proxy’s resolver on 127.0.0.1:53535 asks your network’s real DNS servers (or 1.1.1.1 and 8.8.8.8 if it can’t find them) for the real address, remembers it, and answers 127.0.0.1. Answers expire after 5 seconds, so apps notice changes quickly. Names that don’t exist stay nonexistent.

3. IPv6 and HTTPS-record lookups for captured names get empty answers, so apps connect over IPv4.

4. The app connects to 127.0.0.1 on port 443 or 80. Cloak Proxy accepts connections there only from this Mac, reads the host name from the TLS handshake (SNI) or the Host header, and connects to the real address it remembered.

5. The connection is handled like an HTTPS tunnel: decrypted, recorded and run through your debugging tools. DNS Spoofing rules take priority over the remembered address.

Only this Mac can ask Cloak Proxy’s resolver. Lookups for other domains never reach it.

While Cloak Proxy is closed

Captured domains resolve through Cloak Proxy, so without help they’d stop working whenever Cloak Proxy isn’t running. A background helper covers that gap:

• It’s a per-user LaunchAgent, ~/Library/LaunchAgents/com.subcloak.cloakproxy.dns-standby.plist, that runs cloakctl dns-standby from inside the app at login. No password is needed to install it.
• While Cloak Proxy is closed, the helper answers lookups for captured domains with their real addresses, so apps connect normally. Their requests aren’t recorded.
• When Cloak Proxy is running, the helper steps aside and Cloak Proxy answers.
• It exits by itself once no Cloak Proxy resolver files are left, and macOS restarts it if it crashes.

Cloak Proxy installs the helper when you capture your first app, refreshes it each time it opens (so it always points at your current copy of the app), and removes it when you stop the last capture.

Before you delete Cloak Proxy

Stop every capture before you delete the app. If the resolver files stay behind without Cloak Proxy and its helper, the captured domains stop resolving for every app on your Mac. If that already happened, see Clean up after deleting the app.

Pinned apps

Apps that pin their certificates reject Cloak Proxy’s certificate, so they can’t be decrypted. For captured domains, Cloak Proxy detects this on the first failed handshake, records the failure with a note that it now passes the host through, and relays that host untouched from then on, so the app keeps working. The connections still appear in the list as encrypted tunnels, and the capture sheet lists those hosts under Pinned (passed through):. Cloak Proxy forgets this when the proxy restarts, and tries to decrypt the host again.

Limits

Limit	Why
Only ports 443 (HTTPS) and 80 (HTTP)	Cloak Proxy takes over captured connections on these two ports. Don’t capture a domain the app reaches on another port.
IPv4 only	IPv6 lookups for captured names get empty answers so apps fall back to IPv4.
Affects every app on the Mac	/etc/resolver applies system-wide to the domain and its subdomains.
The app must look the name up	Apps that connect to a fixed IP address, or resolve names with their own DNS client, don’t use /etc/resolver and can’t be captured this way.
Ports 80 and 443 must be free	If another program on your Mac, such as a local web server, already uses one of them, the sheet shows an error such as Capture listener on port 443: followed by the reason.
Pinned certificates	See Pinned apps.
The app must reconnect	Apps cache addresses. Quit and reopen the app after you capture or stop capturing.

If something goes wrong

Message	What to do
Couldn’t update /etc/resolver: followed by an error	macOS refused the change. Try again and enter your password.
Capture listener on port 443: or port 80: followed by an error	Another program uses that port. Quit it, then reopen Cloak Proxy.
Capture resolver on port 53535: followed by an error	Another program uses port 53535. Quit it, then reopen Cloak Proxy.
The app’s requests still don’t appear	Quit and reopen the app. Check that you captured the domains it actually uses: add more from its direct connections, or look at the other suggestions.
Requests appear but fail with a TLS handshake error	The app doesn’t trust the Cloak Proxy certificate, or it pins certificates. See Pinned apps.

Problems are also written to ~/Library/Logs/CloakProxy/cloak-proxy.log.

Automate it

Tool	What it does
MCP bypassing_apps	Lists apps with direct connections and apps already captured.
MCP suggest_capture_domains	Returns the recommended and other domains for an app.
MCP open_capture	Opens the capture sheet in Cloak Proxy so you can confirm with your password.
cloakctl bypass-scan [--port N]	Prints apps connecting directly instead of through the proxy on that port (default 9090).

Capturing always needs your Mac password, so an AI assistant can prepare a capture but you confirm it in the app. See MCP server and cloakctl.

Related

Capture an app that ignores the proxyA step-by-step guide with a real app.

How it worksDNS capture and the background helper, explained.

Network settingsReverse proxies for apps with no proxy support.

SSL ProxyingPinned apps and TLS handshake failures.