Capturing browser and Electron apps

A capturing browser is a Chrome, Chromium, Edge, Brave or Firefox window with its own profile, already pointed at Cloak Proxy and trusting its certificate. Your everyday browser profile, its extensions and sign-ins, and the Mac’s proxy settings don’t change. It’s the quickest way to capture a web app, including one running on localhost, without turning on macOS capture for every other app. Add the browser extension to see which tab, frame and script made each request.

It’s also the way to inspect a browser without breaking sign-ins: SSL Proxying for a whole browser decrypts everything it loads, which Google sign-in and Cloudflare-protected sites refuse (see Decrypting a browser).

Electron apps (chat clients, editors, your own desktop app) often ignore the macOS proxy. Cloak Proxy can start them with the flags and variables that send both their windows and their Node.js side through the proxy.

12345

Capturing Browser in Device & Runtime Setup.

1. Opens the browser with its capture profile
2. How it trusts the certificate
3. The page it opens
4. Send localhost through the proxy too
5. Capture browsers Cloak Proxy opened

×

Open a capturing browser

1. Choose Proxy › Open Capturing Browser and pick a browser. The first one in the list is ⇧ ⌘ B.

   Or open Proxy › Device & Runtime Setup…, choose Capturing Browser in the sidebar and click Open next to a browser.

2. A new browser window opens. Use the site or web app you want to capture.

3. Its requests show in the traffic list under the browser’s name in the Apps sidebar. To read HTTPS, add the hosts to SSL Proxying as usual (right-click a request › Enable SSL Proxying).

You can also type Open Capturing in Search Everything (⇧ ⌘ A).

The browser window stays open when you close Cloak Proxy, but without the proxy its pages stop loading. Quit it from Open now on the Capturing Browser page, or quit it like any other app.

Which browsers

Cloak Proxy looks in /Applications and ~/Applications for:

Browser	Looks for
Google Chrome	Google Chrome.app
Chromium	Chromium.app
Microsoft Edge	Microsoft Edge.app
Brave	Brave Browser.app
Firefox	Firefox.app, Firefox Developer Edition.app or Firefox Nightly.app

Safari can’t run with its own proxy settings, so it isn’t in the list. Capture Safari with macOS capture.

How the browser trusts the certificate

Each row says how that browser trusts Cloak Proxy’s root certificate:

What the row says	What it means
Trusts the Cloak Proxy certificate in this profile only	Chrome, Chromium, Edge and Brave. Cloak Proxy starts them with --ignore-certificate-errors-spki-list set to the hash of the certificate’s public key. The browser accepts certificates Cloak Proxy makes, in this profile only; the Mac doesn’t need to trust the certificate.
Trusts the certificate through the macOS keychain	Firefox, when this Mac trusts the certificate. The capture profile turns on security.enterprise_roots.enabled, so Firefox accepts what the keychain accepts.
The certificate is added to this profile’s own store	Firefox, when this Mac doesn’t trust the certificate but NSS’s certutil is installed (brew install nss). Cloak Proxy adds the certificate to the capture profile.
HTTPS shows warnings until this Mac trusts the certificate	Firefox with neither. Trust the certificate in Settings › Certificate, or install NSS.

Chromium browsers show a bar saying an unsupported command-line flag is in use. That’s the trust flag; it only affects the capture profile.

Profiles

Each browser has one capture profile, kept between windows, so you stay signed in to the sites you test. It’s separate from your everyday profile: it starts with no extensions, bookmarks or saved passwords.

On the Capturing Browser page	What it does
⋯ › Copy Command	Copies the exact command Cloak Proxy runs, to start the browser yourself or in a script
⋯ › Show Profile in Finder	Shows the capture profile’s folder
⋯ › Clear Capture Profile…	Deletes the capture profile: its sign-ins, cookies, history and cache. Your everyday profile isn’t touched. Not available while that browser is open.

Capture profiles are in ~/Library/Application Support/CloakProxy/Capture Browsers/, one folder per browser.

Options

Option	What it does
Start page	The page the window opens, such as http://localhost:3000. A bare host gets https://, and localhost or 127.x gets http://. Empty opens a blank page.
Capture localhost and 127.0.0.1	On by default. Browsers never send local addresses to a proxy unless told to; with this on they do, so you see requests to your local dev server. Turn it off to leave local requests out.
Start from a fresh profile each time	Each window gets an empty, throwaway profile, deleted when the browser quits. Use it to test a first visit, or to keep sessions apart.

Launch an Electron app with capture

Electron apps found in Applications.

×

1. Open Proxy › Device & Runtime Setup… and choose Electron Apps, or choose Proxy › Launch Electron App with Capture….

2. Click Launch with Capture next to the app. For an app that isn’t listed, click Choose App… and pick it.

3. If the app is running, the button says Relaunch with Capture. Cloak Proxy asks first, quits the app the way ⌘ Q does, then starts it again. Save your work in it first.

The app’s requests show under its name in the Apps sidebar.

Cloak Proxy lists an app when it contains Electron Framework. It starts it with:

• --proxy-server and --proxy-bypass-list=<-loopback>, for its windows (the Chromium side), including requests to localhost;
• --ignore-certificate-errors-spki-list, so its windows trust the certificate;
• HTTP_PROXY, HTTPS_PROXY, NODE_USE_ENV_PROXY=1 and NODE_EXTRA_CA_CERTS, for its Node.js side.

Note

Node.js 24 and later use the proxy variables with NODE_USE_ENV_PROXY. An app’s Node.js side on an older Electron, or one using its own HTTP library, may still connect directly: check Apps that ignore the proxy. From 0.5.0, App Capture New in 0.5.0 captures every process in the app’s bundle, its helpers included, without launch flags.

Some apps only allow one copy and hand a second launch to the first. That’s why Cloak Proxy quits a running copy instead of starting a second one.

From MCP and the command line

AI assistants connected through MCP have two tools for this:

• open_capture_browser opens a capturing browser (browser, url, capture_localhost, fresh_profile), lists the installed browsers (action: "list") or quits the ones Cloak Proxy opened (action: "close").
• launch_electron lists Electron apps (action: "list") or starts one with capture (app). It only quits a running app when you pass relaunch: true.

capture_setup with target: "firefox" or "electron" includes these as steps you can apply.

From Terminal, cloakctl does the same, with or without the app running:

Terminal

cloakctl browser chrome --url http://localhost:3000
cloakctl browser firefox --fresh
cloakctl browser --list
cloakctl electron "Notes Studio" --relaunch
cloakctl electron --list

Add --dry-run to print the command without starting anything. See cloakctl.

Limits

• A capturing browser only sends its own traffic through Cloak Proxy. Other apps, and your everyday browser, aren’t captured unless macOS capture is on.
• HTTP/3 (QUIC) can’t go through an HTTP proxy, so the capture profiles turn it off. Browsers fall back to HTTP/2 or HTTP/1.1.
• Sites that pin certificates in the browser (rare outside some Google services) refuse decryption. Leave them out of SSL Proxying.
• Electron apps that pin certificates, or that run a separate helper with its own networking, may still need DNS capture.

Related

Browser extensionSee which tab and script made each request, and record one tab.

Capture macOS trafficCapture every app on the Mac through the system proxy.

Terminal and runtimesNode.js, Python, Ruby, Go, curl and git in a configured shell.

DockerCapture a Compose project's containers, labelled by service.

DoctorFind out why an app's traffic isn't showing.