Capture macOS traffic

Capturing macOS traffic points your Mac’s system proxy settings at Cloak Proxy, so Safari, Chrome and most Mac apps send their requests through it without any setup. Cloak Proxy saves your previous settings first and puts them back when you turn capture off or quit.

Turn macOS capture on or off

Use any of these. Each one switches between on and off.

Where	Control
Keyboard	⇧ ⌘ P
Menu bar	Proxy › Capture macOS Traffic / Stop Capturing macOS Traffic
Toolbar	macOS Proxy
Status bar	macOS traffic: Off. Click to capture / macOS traffic: On
Empty traffic list	Capture macOS Traffic
Device & Runtime Setup	This Mac › Capture macOS Traffic
Search Everything (⇧ ⌘ A)	Capture macOS Traffic / Stop Capturing macOS Traffic

While the change is applied, the status bar reads Updating macOS proxy…. When capture is on, the toolbar pill turns green and reads Capturing, and the status bar shows macOS traffic: On.

12

Device & Runtime Setup › This Mac: macOS capture for apps and browsers, and a configured Terminal for command-line tools.

1. Capture macOS Traffic turns on the system proxy
2. Command-line tools need a configured Terminal instead

×

Password prompts

Cloak Proxy changes the settings with macOS’s networksetup tool. On most Macs that needs no password. If macOS requires administrator rights to change network settings, it asks for your password once each time Cloak Proxy turns the proxy on or off.

What changes on your Mac

When you turn capture on, Cloak Proxy does this for every enabled network service (Wi-Fi, Ethernet, Thunderbolt Bridge and so on):

Setting in System Settings › Network › Details… › Proxies	Set to
Web proxy (HTTP)	On, 127.0.0.1, Cloak Proxy’s port (9090 by default)
Secure web proxy (HTTPS)	On, 127.0.0.1, Cloak Proxy’s port
Bypass proxy settings for these hosts & domains	Your enabled bypass list entries

Other proxy settings, such as SOCKS or automatic proxy configuration, aren’t touched.

Before it changes anything, Cloak Proxy saves a snapshot of each service’s HTTP proxy, HTTPS proxy and bypass list. If you turn capture on again while a snapshot is still saved, it keeps the original snapshot, so your real settings are never overwritten with Cloak Proxy’s own.

Your previous settings come back

Cloak Proxy restores the snapshot when you:

• turn macOS capture off,
• quit Cloak Proxy with ⌘ Q or Cloak Proxy › Quit Cloak Proxy,
• change the port or Allow other devices to connect and click Apply & Restart Proxy (it turns the proxy off, restarts, and turns it back on with the new settings).

Services that had no proxy before get their HTTP and HTTPS proxies turned off. Services that pointed at another proxy, such as a corporate proxy, point at it again.

Closing the main window doesn’t stop capture. Cloak Proxy keeps running, and you bring the window back from the Dock.

Using a corporate proxy

If your Mac normally uses a corporate proxy, Cloak Proxy replaces it while capturing. Set it as Cloak Proxy’s external proxy so the requests Cloak Proxy reads and forwards still go through it. Encrypted connections that Cloak Proxy only relays connect to the server directly.

Turn capture on automatically

Settings › General › Capture macOS traffic when Cloak Proxy opens is on by default. Cloak Proxy then turns on macOS capture every time it starts, as long as the proxy is listening. Turn the switch off if you’d rather start capture yourself, for example when you only debug devices or a configured Terminal.

1

Settings › General.

1. Capture macOS traffic when Cloak Proxy opens

×

The proxy guard restores settings after a crash

While macOS capture is on, apps that follow the system proxy can only reach the internet through Cloak Proxy. If Cloak Proxy stopped without restoring your settings, they’d be cut off. Cloak Proxy prevents that:

Situation	What happens
You quit normally	Cloak Proxy restores the snapshot before it exits. macOS can’t end it silently while capture is on: Cloak Proxy opts out of automatic termination.
The process gets SIGTERM, SIGINT or SIGHUP (kill, Ctrl C in a terminal, closing that terminal)	Cloak Proxy restores the snapshot, then exits.
You force quit Cloak Proxy, or it crashes	The proxy guard restores the snapshot.
You reopen Cloak Proxy while the settings still point at it	Cloak Proxy keeps the saved snapshot and restores it when you next stop capture or quit.

The proxy guard is a small helper, cloakctl proxy-guard, that Cloak Proxy starts the first time it turns on macOS capture. It runs in its own session, so it outlives the app. When Cloak Proxy’s process ends, the guard waits two seconds, then restores your saved settings only if the macOS proxy still points at Cloak Proxy’s port and nothing is listening there. If you changed the port in Settings, it checks the new one. If no snapshot was saved, it turns the HTTP and HTTPS proxies off. It writes what it did to ~/Library/Logs/CloakProxy/cloak-proxy.log.

If the Mac loses power

If the Mac shuts down before anything can run (a power cut or a forced restart), the proxy settings still point at Cloak Proxy when the Mac starts again, and apps can’t connect until it’s running. Open Cloak Proxy, then quit it or press ⇧ ⌘ P to restore your settings. Or turn off Web proxy (HTTP) and Secure web proxy (HTTPS) in System Settings › Network › Details… › Proxies.

Which apps follow the macOS proxy

Follows the macOS proxy	Doesn’t
Safari, Chrome and other browsers that use system settings	Most command-line tools, such as curl, Node.js, Python, Ruby and Go programs. Use a configured Terminal.
Most Mac apps that use Apple’s networking (URLSession)	Java programs, Dart and Flutter apps, and some Electron apps. See Java, Firefox, Docker, Flutter and Electron.
	Apps with their own network stack (gRPC, Network.framework) and some payment and security SDKs. See Apps that ignore the proxy.
	Phones, simulators and other computers. See Devices.

For apps with no proxy support at all, a reverse proxy can also work.

Exclude hosts with the bypass list

The bypass list names hosts that skip Cloak Proxy entirely while macOS capture is on. Requests to them go straight to the network and never appear in the list. Use it for hosts you never want to touch, such as an internal service that breaks behind a proxy.

123

Settings › Bypass, with the three default entries.

1. Turn an entry on or off without deleting it
2. Click a host to edit it
3. Type a host and press Return or click Add

×

1. Open Cloak Proxy › Settings… (⌘ ,) and click Bypass.

2. Type a host in the field at the bottom, such as *.internal.example.com, and press Return or click Add.

3. Turn macOS capture off and on again (⇧ ⌘ P twice). Bypass changes apply the next time you turn the macOS proxy on.

Control	What it does
On	Includes the entry. Entries that are off aren’t sent to macOS.
Host	The host or pattern. Click it to edit.
Add	Adds what you typed in the field.
Remove	Removes the selected entry.

The defaults are localhost, *.local (Bonjour and local network names) and 169.254/16 (link-local addresses). Cloak Proxy writes the entries to macOS exactly as you type them, and macOS decides what matches. macOS accepts host names, wildcards like *.example.com, and IP ranges like 169.254/16.

Note

The bypass list is part of the macOS proxy settings, so it only affects apps that follow the macOS proxy. Devices, configured Terminals and other clients that you point at Cloak Proxy directly aren’t affected. To hide requests from the list without bypassing the proxy, use a filter or the Allow List.

If capture doesn’t turn on

Message or symptom	Cause and fix
Cloak Proxy set the macOS proxy, but macOS doesn’t report it as active. A VPN or a configuration profile may be overriding proxy settings.	A VPN client or a device-management profile controls the proxy settings. Disconnect the VPN or ask your administrator. The log file named in the message has details.
Could not change the system proxy: followed by an error	macOS refused the change, or you cancelled the password prompt. Try again and enter your password.
The macOS Proxy button and status bar control are dimmed	The proxy isn’t listening. Hover the red Not listening pill for the reason, and change the port if it’s in use.
Capture is on but an app’s requests don’t appear	The app ignores the macOS proxy. Check Not Using the Proxy in the sidebar.

You can also turn capture on and off from the command line or an AI assistant with the MCP tool set_macos_proxy. See MCP server.

Related

SSL ProxyingDecrypt HTTPS from the apps you capture.

Apps that ignore the proxyCapture apps that connect directly.

Terminal and runtimesCapture curl, Node, Python and more.

How it worksThe proxy, the snapshot and the guard, explained.