# Web companion

> Watch the traffic Cloak Proxy captures on your Mac live in Safari or Chrome on an iPhone, iPad, Android phone or another computer, with no app to install.

Source: https://docs.subcloak.com/cloak-proxy/devices/web-companion/

Added in Cloak Proxy 0.3.0.

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.

*[Screenshot: The web companion in a browser at tablet width: a list of requests with method, status, path, host, app, duration and size on the left, and the selected request's headers on the right with the Authorization value shown. The web companion on a tablet. On a phone, the list fills the screen and a request opens on top of it.]*

> **Showing a colleague?:**
> To show your traffic to a colleague rather than on your own devices, use [Live sharing](https://docs.subcloak.com/cloak-proxy/sessions/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-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](https://docs.subcloak.com/cloak-proxy/devices/iphone-and-ipad/) or [Android](https://docs.subcloak.com/cloak-proxy/devices/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](https://docs.subcloak.com/cloak-proxy/devices/iphone-and-ipad/) or [Android](https://docs.subcloak.com/cloak-proxy/devices/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](#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](https://docs.subcloak.com/cloak-proxy/tools/overview/).

When a [Breakpoint](https://docs.subcloak.com/cloak-proxy/tools/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 overview](https://docs.subcloak.com/cloak-proxy/devices/overview/): Send traffic from phones, simulators and runtimes through Cloak Proxy.
  - [iPhone and iPad](https://docs.subcloak.com/cloak-proxy/devices/iphone-and-ipad/): Capture an iPhone's own apps and trust the certificate.
  - [Inspector](https://docs.subcloak.com/cloak-proxy/inspect/inspector/): Every tab of the Mac's inspector.
  - [Security and privacy](https://docs.subcloak.com/cloak-proxy/reference/security-and-privacy/): What stays on your Mac and who can reach it.