# Capture apps that ignore the proxy

> Send Go and Rust tools, command-line tools, Electron apps and other Mac apps that skip the macOS proxy through Cloak Proxy with its network extension, app by app, and remove it again.

Source: https://docs.subcloak.com/cloak-proxy/capture/capture-apps-that-ignore-the-proxy/

Added in Cloak Proxy 0.5.0.

Some Mac apps never look at the macOS proxy setting, so their requests don't show up even while Cloak Proxy [captures macOS traffic](https://docs.subcloak.com/cloak-proxy/capture/macos-traffic/). Most tools written in Go or Rust, `curl` and other command-line tools without proxy variables, Node.js scripts, and many Electron apps open their connections straight to the internet. **App Capture** sends the apps you pick through Cloak Proxy anyway. It uses a network extension that macOS runs for Cloak Proxy: every TCP connection one of those apps opens goes to Cloak Proxy first, which then treats it like any other proxied connection. Decryption follows [SSL Proxying](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/), and your rules, the [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/) and the Apps sidebar work as usual.

App Capture is off until you turn it on, works app by app, and leaves every other app alone.

*[Screenshot: Device & Runtime Setup on the App Capture page: the network extension is on and capturing ShopApp and curl, the Apps list shows ShopApp and curl with Captured labels and deploy-tool turned off, 214 connections captured, the Block HTTP/3 option, notes on what isn't captured, and a Remove Extension button. App Capture with two apps captured. The switch next to each app turns it off without removing it.]*

> **Tip:**
> Try the simpler ways first when they fit: a [capturing browser](https://docs.subcloak.com/cloak-proxy/devices/capturing-browser/) for websites, **Launch with Capture** for an Electron app, or a [Terminal window set up for Cloak Proxy](https://docs.subcloak.com/cloak-proxy/devices/terminal-and-runtimes/) for tools that read `HTTPS_PROXY`. They need no system extension. App Capture is for apps that ignore all of these.

## What you need

| Requirement | Details |
|---|---|
| macOS | macOS 14 Sonoma or later |
| Cloak Proxy | The download from [subcloak.com](https://subcloak.com/apps/cloak-proxy), in the **Applications** folder. macOS installs system extensions only from apps in Applications. Builds you make yourself don't include the network extension. |
| Your approval | macOS asks once to allow the extension and once to allow its proxy configuration. Allowing the extension needs an administrator's password. On managed Macs, a configuration profile can allow the extension in advance: see [Deploy to a team's Macs](https://docs.subcloak.com/cloak-proxy/getting-started/deploy-to-a-team/#pre-approve-the-network-extension). |
| The certificate | To see inside HTTPS, the app must trust the [Cloak Proxy certificate](https://docs.subcloak.com/cloak-proxy/capture/certificate/), as for any other app. Without it, the app's connections still show as encrypted tunnels. |

## Turn on App Capture

*[Screenshot: The App Capture page before the extension is installed: Not installed with an Install Extension button, No apps picked yet with an Add App menu, and ShopApp listed under Connecting around the proxy now with an Add button. Before you start: the extension isn't installed, and ShopApp is connecting around the proxy.]*

1. Open **Proxy › Device & Runtime Setup…** and choose **App Capture** in the sidebar.

   Or click an app under **Not using the proxy** in the sidebar and choose **Use App Capture**, or click **Capture all its traffic** in the [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/).

2. Under **Apps**, click **Add App** and pick the app:

   - **Connecting around the proxy**: apps Cloak Proxy saw connecting straight to the internet.
   - **In the traffic list**: apps that already sent requests through Cloak Proxy.
   - **Running**: apps open now.
   - **Choose App or Tool…**: any `.app`, or a command-line tool such as `/usr/bin/curl` or `~/go/bin/deploy-tool`. Links are followed, so picking `/opt/homebrew/bin/terraform` adds the file it points to.

3. Click **Install Extension…**. macOS may tell you that the extension was blocked and needs your approval.

4. Allow the extension in System Settings. The status reads **Waiting for your approval** until you do, with the steps for your macOS version, and **Open System Settings** takes you there.

   **macOS 15 and later**

   Open **System Settings › General › Login Items & Extensions**, click <kbd>ⓘ</kbd> next to **Network Extensions**, and turn on **Cloak Proxy**. Enter your password when asked.

   **macOS 14**

   Open **System Settings › Privacy & Security**. Next to the message about system software from Cloak Proxy, click **Allow** and enter your password.

5. Back in Cloak Proxy, macOS asks whether Cloak Proxy may add proxy configurations (**"Cloak Proxy" Would Like to Add Proxy Configurations**). Click **Allow**.

6. The status turns green and reads **On**, followed by the apps it captures. Quit and reopen the apps you picked, so connections they already had open go through Cloak Proxy too.

Requests from the captured apps appear in the traffic list under each app's name, with its icon. In the Doctor's **Connections** tab their connections say **App capture**. A **Captured** label next to an app in the list means its connections went through Cloak Proxy recently.

*[Screenshot: The App Capture page while the network extension waits for approval: an orange triangle, Waiting for your approval, the steps in System Settings and an Open System Settings button. Until you allow the extension in System Settings, the picked apps connect directly.]*

## The App Capture page

| Part | What it does |
|---|---|
| **Network extension** | The extension's state and the next step: **Not installed** with **Install Extension…**, **Waiting for your approval** with **Open System Settings**, **Off** with **Turn On**, **On** with **Turn Off**, or **Stopped** with the reason and **Try Again**. **Move Cloak Proxy to Applications** (with **Show in Finder**) means the app runs from somewhere else, and **Not in this copy of Cloak Proxy** means a build without the extension. |
| **Apps** | The apps you picked, with their path. The switch turns one app off without removing it; <kbd>⊖</kbd> removes it. The count of connections captured since the extension started appears while it's on. **Add App** adds another. |
| **Connecting around the proxy now** | Apps with direct connections right now, with **Add**. Shown when there are any. |
| **Block HTTP/3 for these apps** | On by default. See [HTTP/3](#http3). |
| **Remove Extension…** | Turns App Capture off and removes the extension from macOS. The picked apps are kept. See [Remove App Capture](#remove-app-capture). |

### How apps are matched

Cloak Proxy matches a connection to an app you picked in two ways:

- **By code signature.** An app matches its bundle identifier, and its helpers match identifiers under it, so picking an app also captures its helper processes (`com.example.chat` also matches `com.example.chat.helper`). A command-line tool matches its signing identifier, such as `com.apple.curl`.
- **By location.** Anything that runs from inside the app's bundle matches, and a tool matches its own file.

Cloak Proxy itself, `cloakctl` and the extension are never captured, so the proxy's own connections can't loop back into it.

## When Cloak Proxy isn't running

The extension only captures while Cloak Proxy is open and listening. When you quit Cloak Proxy, it stops the extension, and the picked apps connect directly again. If Cloak Proxy crashes or is force quit, the extension notices within 15 seconds and steps aside; connections opened in those seconds fail once and the app retries. The next time Cloak Proxy opens, App Capture starts again if it was on.

When you update Cloak Proxy, macOS replaces the extension with the new version's by itself. You don't approve it again, and App Capture keeps the apps you picked.

## What App Capture doesn't capture

| Limit | Details |
|---|---|
| UDP | Only TCP connections are captured. DNS, calls, games and other UDP traffic go out as usual. |
| HTTP/3 | HTTP/3 (QUIC) runs over UDP. With **Block HTTP/3 for these apps** on, apps fall back to HTTPS over TCP, which is captured. See [HTTP/3](#http3). |
| Pinned certificates | Apps that pin their servers' certificates refuse Cloak Proxy's. Cloak Proxy then passes those connections through untouched and still lists them. See [Certificate pinning](https://docs.subcloak.com/cloak-proxy/capture/doctor/#certificate-pinning). |
| VPNs and other network extensions | A VPN app, a firewall or another proxy that uses its own network extension may take the traffic before App Capture does, or route it around. If captured requests stop arriving, disconnect the VPN or turn off the other extension while you capture. |
| Safari and WebKit apps | Safari and apps that show web pages load them in a shared macOS process, not the app itself. They follow the macOS proxy, so [macOS capture](https://docs.subcloak.com/cloak-proxy/capture/macos-traffic/) covers them. |
| Connections to this Mac | Connections to `localhost` and `127.0.0.1` are never captured. |
| Other devices | App Capture works on this Mac only. For an iPhone or iPad, see [iPhone and iPad](https://docs.subcloak.com/cloak-proxy/devices/iphone-and-ipad/). |

### HTTP/3

HTTP/3 (QUIC) runs over UDP, which no HTTP proxy can carry. With **Block HTTP/3 for these apps** on (the default), the extension refuses the picked apps' QUIC connections, and apps fall back to HTTPS over TCP, usually within a second. Turn it off for an app that only speaks HTTP/3; its traffic then stays hidden.

## App Capture or DNS capture?

[Capturing an app's domains](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/) also gets apps that ignore the proxy into Cloak Proxy, by answering the DNS lookups for their domains.

| | App Capture | Capture its domains |
|---|---|---|
| What's captured | Every TCP connection the picked apps open, to any server and port | Connections to the captured domains on ports 443 and 80, from every app |
| Setup | Pick the app. macOS asks once to allow the extension | Pick the domains. macOS asks for your password each time they change |
| Needs | The Cloak Proxy download, in Applications | Any build |
| Apps that connect to IP addresses | Captured | Missed (no DNS lookup) |

## Use it from an assistant or Terminal

An AI assistant connected through the [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/) reads the state with `app_capture_status` and changes it with `set_app_capture`. Removing an app, turning one off, turning App Capture off and the HTTP/3 option apply at once. Adding an app or turning App Capture on never happens on its own: Cloak Proxy shows the request at the top of the App Capture page, and nothing changes until you click **Allow**.

*[Screenshot: The App Capture page with a request at the top: Claude Code asks to capture ShopApp's traffic with the network extension, with Don't Allow and Allow buttons. An assistant's request waits for you.]*

In Terminal:

```bash title="Terminal"
cloakctl app-capture                         # the state and the picked apps
cloakctl app-capture capture /usr/bin/curl   # ask to capture curl (you allow it in Cloak Proxy)
cloakctl app-capture remove curl
cloakctl app-capture off
cloakctl app-capture quic off                # stop blocking HTTP/3
```

See [cloakctl](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/#app-capture) and the [MCP tools reference](https://docs.subcloak.com/cloak-proxy/automation/mcp-tools-reference/#app_capture_status).

## Try it with curl

`curl` ignores the macOS proxy when you tell it to, which makes it a quick test:

1. Add `/usr/bin/curl` to App Capture (**Add App › Choose App or Tool…**, then <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>G</kbd> and type `/usr/bin/curl`), and turn App Capture on.

2. In Terminal, run:

   ```bash title="Terminal"
   curl --noproxy '*' https://example.com/
   ```

3. The request appears in Cloak Proxy under **curl**. Without App Capture, `--noproxy '*'` would send it straight to the server.

   Over HTTPS it shows as an encrypted tunnel to `example.com` until `example.com` is in [SSL Proxying](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/) and curl trusts the Cloak Proxy certificate. curl doesn't read the macOS keychain: point it at the certificate with `--cacert`, or use a [Terminal window set up for Cloak Proxy](https://docs.subcloak.com/cloak-proxy/devices/terminal-and-runtimes/#the-ca-bundle). Plain `http://example.com/` shows up decoded without either.

## Remove App Capture

To stop capturing for a while, click **Turn Off**. The extension stays installed.

To remove the extension from macOS, click **Remove Extension…** on the App Capture page and confirm. Cloak Proxy removes its proxy configuration and asks macOS to remove the extension; macOS may ask for your password. The page then says **The network extension was removed**: it stops at once, and macOS deletes its files at your next restart (`systemextensionsctl list` shows it as waiting to uninstall until then). If the page says **The network extension is removed when you restart your Mac**, restart to finish.

Do this before you [uninstall Cloak Proxy](https://docs.subcloak.com/cloak-proxy/getting-started/install/#uninstall-cloak-proxy-completely). If you already deleted the app, check **System Settings › General › Login Items & Extensions › Network Extensions** (macOS 15 and later), or run `systemextensionsctl list` in Terminal: a leftover extension shows as `com.subcloak.cloakproxy.transparent-proxy`. Reinstall Cloak Proxy into Applications, then remove it as above.

If you installed Cloak Proxy with Homebrew, `brew uninstall --cask cloak-proxy` removes the extension for you before it deletes the app.

For scripts, the app removes the extension without opening a window or starting the proxy:

```bash title="Terminal"
"/Applications/Cloak Proxy.app/Contents/MacOS/CloakProxy" --remove-network-extension
```

It exits with 0 when the extension is removed or wasn't installed, and 1 when macOS refuses or doesn't answer within two minutes. macOS may ask for an administrator's password.

The proxy configuration Cloak Proxy adds is listed in **System Settings › Network** too. Removing the extension removes it as well.

> **Teams:**
> Administrators can allow the extension ahead of time with a configuration profile, so people aren't asked to approve it in System Settings. macOS still asks each person once about the proxy configuration. See [Deploy to a team's Macs](https://docs.subcloak.com/cloak-proxy/getting-started/deploy-to-a-team/#pre-approve-the-network-extension).

## Related

  - [Apps that ignore the proxy](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/): Capture an app's domains with DNS capture, in any build.
  - [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/): Find out why an app's traffic isn't showing, with a fix for each finding.
  - [SSL Proxying](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/): Choose which hosts are decrypted.
  - [Security and privacy](https://docs.subcloak.com/cloak-proxy/reference/security-and-privacy/#the-network-extension): What the network extension can see and do.