Web companion

The web companion shows the traffic Cloak Proxy captures on your Mac in a browser on another device: Safari on an iPhone or iPad, Chrome on an Android phone, or any browser on another computer on the same network. Nothing is installed on the device. Use it to keep an eye on requests while you tap through an app on a phone, or to look at a request on a tablet while your Mac’s screen is busy.

1234

The web companion on a tablet. On a phone, the list fills the screen and a request opens on top of it.

1. Pause or resume recording, and open the debugging tools
2. Search, and filter by method, status and app
3. Requests arrive live, newest first
4. Overview, Headers, Body, Raw and Timing

×

Showing a colleague?

To show your traffic to a colleague rather than on your own devices, use Live sharing: it uses the same listener, needs no pairing, and is read-only and limited to the requests you choose.

Turn on the web companion

1. On the Mac, open Cloak Proxy › Settings… and click the Companion tab.

2. In Web browsers, turn on Allow browsers to connect.

   Cloak Proxy starts serving the web companion on port 9093 and shows its Address, for example https://192.168.1.20:9093. If macOS asks whether Cloak Proxy may accept incoming network connections, click Allow.

3. Click Pair browser…. A sheet shows a QR code, the address and a 6-digit code. They work for 5 minutes and for one browser.

4. On the other device, connect it to the same network as the Mac, then do one of these:

   • Point the camera at the QR code and open the link. The page pairs on its own.
   • Open the address in the browser and type the 6-digit code.

5. If the browser warns about the certificate, continue to the page (see The certificate warning).

   The sheet on the Mac shows Paired with and the browser’s name, and the browser shows the Mac’s traffic.

The browser stays paired until you remove it on the Mac or choose Disconnect this browser on the page. Next time, open the same address; there’s no code to type.

Note

The web companion and the proxy are separate. Viewing traffic in a browser doesn’t route that device’s traffic through Cloak Proxy. To capture the phone’s own apps, set its Wi-Fi proxy as in iPhone and iPad or Android.

Settings

Setting	What it does
Allow browsers to connect	Serves the web companion on every network interface. Off by default. Turning it off disconnects every browser right away; paired browsers reconnect without a new code when you turn it back on.
Port	The port for the web companion, 9093 by default. Type a port and click Apply.
Address	The address to open on the other device. It follows the Mac’s current network address.
Pair browser…	Opens the QR code and the 6-digit code. Available while the web companion is on.

The same address also works with the Mac’s local name, for example https://Adas-MacBook-Pro.local:9093, which keeps working when the Mac’s IP address changes. The Pair browser sheet shows it under the code.

The certificate warning

The web companion uses HTTPS with a certificate issued by your Mac’s Cloak Proxy certificate authority, for the Mac’s addresses and its .local name. A device that already trusts the Cloak Proxy certificate, because you set it up to have its HTTPS decrypted, opens the page with no warning.

Other devices don’t know that certificate authority, so the browser warns once. Continue to the page:

Safari on iPhone or iPad

On This Connection Is Not Private, tap Show Details, then visit this website, then Visit Website.

Chrome

On Your connection is not private, tap Advanced, then Proceed to 192.168.1.20 (unsafe).

Firefox

On Warning: Potential Security Risk Ahead, tap Advanced…, then Accept the Risk and Continue.

To stop the warning for good, trust the Cloak Proxy certificate on the device. Once paired, open Tools on the page and tap Download the Mac’s certificate, then install and trust it as in iPhone and iPad or Android. Only do this on your own devices: a device that trusts the certificate lets your Mac decrypt its HTTPS traffic when it uses the Mac as its proxy.

Check the address before you continue

Continue past the warning only for your Mac’s address as shown in Settings › Companion. The QR code always opens the right address.

Use the web companion

The page has the same layout on every device: a toolbar, the traffic list, and the inspector. On a phone, the list fills the screen and a request opens on top of it; tap Requests or swipe back to return. On a tablet or a computer, the list and the inspector sit side by side. Everything follows the device’s light or dark appearance.

The toolbar

Item	What it shows or does
Mac name and dot	The Mac you’re connected to. Green: connected and recording. Orange: recording is paused on the Mac. Red: the connection dropped; the page reconnects on its own and shows Reconnecting….
Pause and Resume	Pauses or resumes recording on the Mac, as Pause Recording does there.
Tools	Opens the tools panel.

The traffic list

Requests appear as the Mac captures them, newest at the top. Each row shows:

Part	Meaning
Icon	The app that sent the request (the Mac’s app icon, or its first letter when there’s none).
Method	GET, POST and so on, colored as on the Mac.
Path	The path and query, or the host for a tunnel.
Status	The status code, colored by class (green 2xx, purple 3xx, orange 4xx, red 5xx), Active while in progress, Failed, or Tunnel for a connection that wasn’t decrypted.
Host and app	The host, then the app, or the device for traffic from another device.
Time and size	How long the request took and the size of the response body.

The count at the bottom reads, for example, 14 of 97 requests while a search or filter is on. The page keeps the newest 10,000 requests.

Search and filters

• Search matches words in the URL, the method, the status code and the app name. Every word must match.
• Method, Status and App each narrow the list. Status offers 2xx, 3xx, 4xx, 5xx, Failed and In progress.
• Clear turns off the search and every filter.

The inspector

Tap a request to open it. The tabs:

Tab	What it shows
Overview	URL, status, method, protocol, content type and whether it was decrypted; the app, device and client address; body sizes, start time and duration; query parameters; the tools that touched it, its comment and WebSocket message count.
Headers	Request and response headers. Credentials are hidden (see Hidden credentials).
Body	The request or response body. JSON shows as a tree you can expand and collapse, or as formatted Text. Images show as images, other text as text, and binary data as a hex dump of its first bytes. WebSocket connections show their latest 200 messages.
Raw	The request or response as it went over the wire: the first line, the headers, then the body.
Timing	When the request started and finished, its duration, body sizes and protocol.

Body and Raw have a Request and Response switch. Bodies are fetched from the Mac when you open them and decoded from gzip, deflate or Brotli first.

Debugging tools and recording

Tools lists Record traffic and every debugging tool with its number of rules, each with a switch. A switch changes the tool on the Mac right away, exactly like its switch in the Mac’s Tools window. Edit rules on the Mac. See Debugging tools overview.

When a Breakpoint pauses a request, a banner above the list shows it with Continue and Abort. Continue sends it on unchanged. To edit a paused request, use the Breakpoint window on the Mac.

Hidden credentials

Sensitive header values are hidden by default, as in the Mac’s header columns: Authorization, Proxy-Authorization, X-API-Key, API-Key, Cookie, Set-Cookie, and headers whose names contain token, secret, password or auth. The page shows only the scheme and the last four characters, for example Bearer ••••c2ln, and cookie names without their values. Tap Show next to one to see it, or Show credentials in Raw.

Remove a browser

Paired browsers appear in Settings › Companion › Paired devices with a globe icon, the date they paired and when they were last seen. Click Remove to disconnect one. It stops working right away and needs a new code to connect again.

On the device itself, open Tools and tap Disconnect this browser.

Security

A paired browser sees everything Cloak Proxy captures

A paired browser can read all captured traffic, including headers, bodies, cookies and tokens, and can turn debugging tools and recording on or off and continue or abort paused requests. Pair only your own devices, and remove browsers you no longer use.

• Pairing needs someone at the Mac to open Pair browser…. A code works for 5 minutes and for one browser. After five wrong codes the code stops working; open the sheet again for a new one.
• The session is a cookie the page’s scripts can’t read (HttpOnly), sent only over HTTPS (Secure) and only by the page itself (SameSite=Strict). The Mac keeps only a hash of it.
• The page refuses requests from other websites, can’t be embedded in another page, and loads nothing from the internet.
• Bodies stay in the page’s memory while it’s open. Nothing is saved in the browser.
• Turn off Allow browsers to connect when you’re done.

Troubleshooting

Problem	What to do
The page doesn’t load	Check that the device is on the same network as the Mac and that Allow browsers to connect is on. Guest and public Wi-Fi networks often block devices from reaching each other. If the macOS firewall is on, allow incoming connections for Cloak Proxy in System Settings › Network › Firewall › Options.
Wrong code	Type the code the Mac shows now. Codes change each time you open Pair browser….
Too many wrong codes	Close the sheet on the Mac and open Pair browser… again for a new code, or scan the QR code.
Pairing isn’t open on the Mac	The code expired or was used. Open Pair browser… on the Mac again.
The page asks for a code again	The browser was removed on the Mac, or the browser cleared its cookies. Pair again.
The address changed	The Mac got a new IP address. Open the new address from Settings › Companion, or use the .local address.

Related

Devices and runtimes overviewSend traffic from phones, simulators and runtimes through Cloak Proxy.

iPhone and iPadCapture an iPhone's own apps and trust the certificate.

InspectorEvery tab of the Mac's inspector.

Security and privacyWhat stays on your Mac and who can reach it.