# Capturing browser and Electron apps

> Open Chrome, Edge, Brave or Firefox in its own profile that already uses Cloak Proxy and trusts its certificate, and start Electron apps with capture.

Source: https://docs.subcloak.com/cloak-proxy/devices/capturing-browser/

Added in Cloak Proxy 0.4.0.

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](https://docs.subcloak.com/cloak-proxy/devices/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](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/#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.

*[Screenshot: Device & Runtime Setup on the Capturing Browser page: Google Chrome (open), Microsoft Edge, Brave and Firefox, each with an Open button and how it trusts the certificate; options for the start page, capturing localhost and fresh profiles; and the Chrome window that's open now with a Quit button. Capturing Browser in Device & Runtime Setup.]*

## Open a capturing browser

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

   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** (<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>A</kbd>).

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](https://docs.subcloak.com/cloak-proxy/capture/macos-traffic/).

## 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

*[Screenshot: The Electron Apps page listing four Electron apps with their versions and Electron versions, each with a Launch with Capture button. 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 <kbd>⌘</kbd> <kbd>Q</kbd> 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](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/). From 0.5.0, [App Capture](https://docs.subcloak.com/cloak-proxy/capture/capture-apps-that-ignore-the-proxy/) (added in Cloak Proxy 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](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/) have two tools for this:

- [`open_capture_browser`](https://docs.subcloak.com/cloak-proxy/automation/mcp-tools-reference/#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`](https://docs.subcloak.com/cloak-proxy/automation/mcp-tools-reference/#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:

```bash title="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](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/#capture-targets).

## 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](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/).

## Related

  - [Browser extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/): See which tab and script made each request, and record one tab.
  - [Capture macOS traffic](https://docs.subcloak.com/cloak-proxy/capture/macos-traffic/): Capture every app on the Mac through the system proxy.
  - [Terminal and runtimes](https://docs.subcloak.com/cloak-proxy/devices/terminal-and-runtimes/): Node.js, Python, Ruby, Go, curl and git in a configured shell.
  - [Docker](https://docs.subcloak.com/cloak-proxy/devices/docker/): Capture a Compose project's containers, labelled by service.
  - [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/): Find out why an app's traffic isn't showing.