Capture traffic

SSL Proxying

Choose which HTTPS traffic Cloak Proxy decrypts, by app or by host with wildcards, and understand locked tunnels, pinned apps and TLS handshake failures.

SSL Proxying decides which HTTPS traffic Cloak Proxy decrypts. Out of the box nothing is decrypted: HTTPS passes through as locked tunnels, and you see only the host and connection. Turn SSL Proxying on for an app or a host to read its requests and responses and use the debugging tools on them.

Before you start

Decryption needs the Cloak Proxy root certificate to be trusted wherever the traffic comes from. On this Mac, click Install & Trust… in the banner, or see Root certificate. Phones, simulators and runtimes need it too: see Devices.

The buttons in the app bar and in the inspector stay dimmed until the certificate is trusted on this Mac.

Decrypt everything from one app

Decrypting by app is the quickest way to see an app’s API calls: it covers every host the app connects to, including ones you don’t know about yet.

In the sidebar under Apps, click the app.
In the bar above the traffic list, click Enable SSL Proxying for All Requests from the app.

The bar turns green and reads Decrypting HTTPS from every domain this app connects to. A green open lock appears next to the app in the sidebar.
Use the app. Cloak Proxy closes the app’s open encrypted connections, so it reconnects and the new connections are decrypted.

You can also turn it on from:

the app’s right-click menu in the sidebar: Enable SSL Proxying for All Domains from the app,
a request’s right-click menu in the traffic list: Enable SSL Proxying for All Domains from the app,
a locked tunnel’s inspector: Enable all domains from the app.

To turn it off, click Disable SSL Proxying in the app bar, or choose Disable SSL Proxying for the app from either right-click menu.

Apps are matched by the name shown in the sidebar. Helper processes count as their parent app, so decrypting a browser covers its helpers too. Traffic from other devices is labeled with the device’s IP address, so decrypt it by host instead.

Decrypt specific hosts

Decrypt by host when you care about one API rather than everything an app does, or when the traffic comes from a phone or another device.

From the traffic

Right-click a domain in the sidebar and choose Enable SSL Proxying for the host.
Right-click a request in the traffic list and choose Enable SSL Proxying for its host.
Click a locked row and click Enable only the host in the inspector.

The inspector for a locked CONNECT row to www.apple.com from Google Chrome, with buttons Enable only www.apple.com and Enable all domains from Google Chrome — Click a locked row to turn on decryption for its host or its app.
Decrypt this host only
Decrypt every host the app connects to

Cloak Proxy closes the open encrypted connections to that host, so apps reconnect with decryption on. The domain gets a green open lock in the sidebar.

To stop, right-click the domain or a request and choose Disable SSL Proxying for the host. That removes the host’s entry from the list in Settings.

In Settings

Cloak Proxy › Settings… › SSL Proxying lists every host pattern. Use it to add wildcards, or to turn entries off without deleting them.

Settings › SSL Proxying with an empty table of On and Host columns, an explanation of wildcards, and a field with the placeholder api.example.com or *.example.com plus Add and Remove buttons — Settings › SSL Proxying.
On: include or skip the entry
Host: the host or pattern, editable in place
Type a host or pattern
Add it to the list
Remove the selected entry

Open Cloak Proxy › Settings… (⌘ ,) and click SSL Proxying.
Type a host or pattern in the field, such as api.example.com or *.example.com.
Press Return or click Add.

Control	What it does
On	Decrypts hosts matching this entry. Turn it off to keep the entry but stop decrypting.
Host	The host or pattern. Click it to edit.
Add	Adds what you typed.
Remove	Removes the selected entry.

Entries you add in Settings apply to new connections. Already-open tunnels stay encrypted until the app reconnects, so restart the app or wait for it to open new connections. Turning SSL Proxying on from the sidebar, the traffic list or the inspector closes the open tunnels for you.

Write host patterns

Pattern	Matches	Doesn’t match
`api.example.com`	`api.example.com`	`www.example.com`, `example.com`
`*.example.com`	`api.example.com`, `a.b.example.com`	`example.com` (add it separately)
`api-*.example.com`	`api-eu.example.com`, `api-staging.example.com`	`api.example.com`
`api?.example.com`	`api1.example.com`, `api2.example.com`	`api10.example.com`
`example.com:8443`	`example.com` on port 8443 only	`example.com` on port 443
`*`	Every host

Matching ignores letter case. * matches any run of characters, including dots, and ? matches exactly one character. Add :port to match only that port; without it, the pattern matches every port.

What’s always decrypted

Some traffic is decrypted even without an SSL Proxying rule:

Domains you capture through DNS for apps that ignore the proxy, because you set them up to be inspected. Hosts that turn out to pin their certificates are the exception: Cloak Proxy passes them through.
Cloak Proxy’s own certificate page at http://cloak.proxy (also cert.cloak and cloakproxy.local), so devices can download the certificate. See Other devices and access control.

Locked tunnels and pinned apps

Locked tunnels

A row with the method CONNECT and a closed lock is an encrypted tunnel that Cloak Proxy passed through without reading. Its Path column reads Encrypted tunnel (or Connecting… while the connection opens). Hover the lock to see Encrypted. Enable SSL Proxying to see the contents. Click the row to see Encrypted HTTPS to the host, with the buttons described above.

A tunnel row stays in the list for the whole connection. One row can stand for many requests the app sent over that connection. Once you turn on SSL Proxying, new connections appear as individual requests instead.

On ports other than 443, Cloak Proxy looks inside tunnels even without a rule. If the app speaks plain HTTP inside the tunnel, its requests appear as readable http:// rows.

TLS handshake failures

If an app rejects Cloak Proxy’s certificate, the request appears as failed with the message TLS handshake with the client failed. The client probably doesn’t trust the Cloak Proxy CA, or it pins certificates. It has two common causes:

Cause	Fix
The app or device doesn’t trust the Cloak Proxy root certificate	Trust it on this Mac (Install & Trust…), on the device, or in the runtime: Node.js, Python, Java, Firefox and others keep their own trust stores. See Terminal and runtimes and Java, Firefox, Docker, Flutter and Electron. Android apps also need a network security config that trusts user certificates; see Android.
The app pins its certificate	It accepts only its own server’s certificate, so it can’t be decrypted. Turn SSL Proxying off for that host or app so the app works again.

For domains captured through DNS, Cloak Proxy handles pinning for you: after the first failed handshake it adds Cloak Proxy now passes the host through without decrypting it, so the app keeps working to the message, and relays that host untouched until Cloak Proxy restarts.

The green open lock next to an app or domain, and the choice between Enable and Disable in the menus, reflect entries for that exact app or host. A host decrypted through a wildcard such as *.example.com still shows the globe icon in the sidebar, but its requests in the list show the green open lock. To stop decrypting it, edit the wildcard in Settings › SSL Proxying.

Automate SSL Proxying

From an AI assistant, the MCP tool ssl_proxying lists, adds and removes hosts and apps. See MCP server.
For a headless proxy, cloakctl run --ssl HOST_PATTERN and --ssl-app APP_NAME decrypt hosts and apps; repeat them for more than one. See cloakctl.

Root certificateTrust, remove or regenerate the certificate.

Failed requests and tunnelsRead failure messages and tunnel rows.

Apps that ignore the proxyCapture and decrypt apps through DNS.

Debug a mobile appA full walkthrough with a phone.