# Browser extension

> The Cloak Proxy browser extension for Safari, Chrome, Edge, Brave and Firefox tags captured requests with the tab, page, frame and script that made them, records a single tab without a system proxy, and adds console errors to bug reports.

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

Added in Cloak Proxy 0.4.1.

A proxy sees requests, not the browser around them. The Cloak Proxy browser extension fills that in. For each request a tab makes, it tells Cloak Proxy which tab it came from, the page and frame, and what started it: the page's HTML, a script and its line, or a `fetch` call with its JavaScript stack. It can also record one tab without any proxy, and it collects the tab's console errors so a [bug report](https://docs.subcloak.com/cloak-proxy/sessions/report-bug/) shows them next to the failing requests.

The extension talks only to Cloak Proxy on your own computer (`127.0.0.1`), with a key it gets when you pair it. It sends nothing anywhere else, and it isn't in the Chrome Web Store or on addons.mozilla.org: you load it from the copy that comes with Cloak Proxy. In Safari it's already there: from 0.5.0, Cloak Proxy includes it as a Safari extension. (added in Cloak Proxy 0.5.0)

*[Screenshot: The main window filtered by tab:Checkout, with a POST to /v1/checkout/orders selected and the request inspector's Browser tab showing the tab Checkout · ShopApp, its URL, the top frame, Started by script · https://shop.example/assets/api.js:42, and a stack of request, placeOrder, onSubmit and HTMLFormElement.handle. The Browser tab of a request, and the list filtered to one tab.]*

## What it adds

- **Browser tab in the inspector.** The tab's title and URL, the page and frame that made the request, and what started it. For tabs you record in Chrome, the JavaScript stack too.
- **`tab:` in the query bar.** `tab:Checkout` shows the requests one tab made (title or URL). `-tab:*` shows the ones no tab reported, such as the browser's own background traffic. See [Query language](https://docs.subcloak.com/cloak-proxy/inspect/query-language/).
- **Record This Tab.** Captures one tab's requests even when the browser doesn't use Cloak Proxy as its proxy. In Chrome, Edge and Brave it uses the browser's debugging protocol, which also gives response bodies, each request's stack and the tab's console. In Firefox it sends just that tab's requests through Cloak Proxy. Not in Safari, whose extensions can't do either (see [Safari](#safari)).
- **Console errors in bug reports.** Uncaught exceptions, rejected promises and `console.error` calls from your tabs. A bug report lists the ones from around the requests it covers and attaches them as `browser-console.json`.

## Install

The files for Chrome, Edge, Brave and Firefox come with Cloak Proxy. Choose **Proxy › Browser Extension…** and click **Show Extension in Finder**. Cloak Proxy copies them to `~/Library/Application Support/Cloak Proxy/Browser Extension` so the browser keeps loading them from the same place after you update the app.

From 0.5.0, Safari needs no files: the extension is inside the app. (added in Cloak Proxy 0.5.0)

**Safari**

(added in Cloak Proxy 0.5.0)

1. Open Cloak Proxy from your Applications folder at least once. Safari finds the extension then.
2. Choose **Proxy › Browser Extension…** and click **Open Safari Settings** next to **Safari**. Safari opens its **Extensions** settings. (Or choose **Safari › Settings…** and click **Extensions**.)
3. Turn on **Cloak Proxy**.
4. Let it see every website: open a website in Safari, click the Cloak Proxy button in the toolbar, and choose **Always Allow on Every Website**. Safari only lets an extension see the websites you allow, and tagging every tab needs all of them. You can allow single websites instead (or manage the list with **Edit Websites…** in Safari's Extensions settings); requests from the others aren't tagged.

The **Browser Extension** sheet shows **On** next to Safari once it's turned on. The extension updates with Cloak Proxy, so there's nothing to reload after an update.

**Chrome, Edge, Brave**

1. Open `chrome://extensions` (`edge://extensions` in Edge, `brave://extensions` in Brave).
2. Turn on **Developer mode** in the top-right corner.
3. Click **Load unpacked** and choose the **Browser Extension** folder.
4. Pin Cloak Proxy from the puzzle-piece menu so its icon stays in the toolbar.

The browser keeps the extension across restarts. After you update Cloak Proxy, click **Show Extension in Finder** again and then the reload arrow on the extension's card.

**Firefox**

1. Open `about:debugging#/runtime/this-firefox`.
2. Click **Load Temporary Add-on…** and choose `manifest.json` in the **Browser Extension** folder.
3. Open `about:addons`, click Cloak Proxy, and under **Permissions** allow it to access data for all websites. Firefox asks for this separately, and the extension can't see requests without it.

Firefox removes temporary add-ons when it quits, so you load it again after a restart. Firefox Developer Edition and Nightly can keep it: set `xpinstall.signatures.required` to `false` in `about:config` and install the folder as a zip.

## Pair it with Cloak Proxy

1. In Cloak Proxy, choose **Proxy › Browser Extension…** and click **Pair…**. A six-digit code appears. It works once and only for five minutes.
2. In the browser, click the Cloak Proxy icon in the toolbar. Type the code, and the port Cloak Proxy listens on if it isn't 9090, then click **Pair**.

Safari pairs the same way, from its own toolbar button, and doesn't need website access to pair. (added in Cloak Proxy 0.5.0) If the popup says the port isn't answering, check that Cloak Proxy is running.

The browser shows as paired in the sheet, with when it was last seen. **Unpair** there (or in the extension's popup) revokes its key. Each browser and each browser profile pairs separately.

*[Screenshot: The Browser Extension sheet: a Safari row marked On with Open Safari Settings, install instructions for Chrome, Edge, Brave and Firefox with Show Extension in Finder, the pairing code 482 913 with a Cancel button, Chrome extension under Paired browsers, and a console error and a warning from the Checkout · ShopApp tab, with Recording Checkout · ShopApp at the bottom. Proxy › Browser Extension…]*

> **Why pairing:**
> Any web page can send requests to `127.0.0.1`. The key from pairing is how Cloak Proxy knows the extension is the one talking, and requests from a web page's origin are turned away before the key is even checked.

## Tag requests

With tagging on (the popup's **Tag requests with this browser's tabs**, on by default), every request a tab makes is reported to Cloak Proxy: its method, URL and time, and the tab, frame and what started it. Cloak Proxy matches each one to the request it captured with the same method and URL within a few seconds. So tagging needs the browser's traffic to go through Cloak Proxy, for example in a [capturing browser](https://docs.subcloak.com/cloak-proxy/devices/capturing-browser/) or with macOS capture on.

Select a request and open the **Browser** tab in the request inspector. **Show Requests from This Tab** fills in the query bar with `tab:` and the tab's title.

## Record one tab

Click the icon and choose **Record This Tab** when the browser doesn't go through Cloak Proxy and you only care about one tab. The requests appear in the list as they finish, tagged **Recorded by Chrome** (or Edge, Brave), with the tab's context.

- **Chrome, Edge, Brave:** the browser shows a bar saying an extension is debugging the tab while it records. Requests come with their response bodies, decoded, and the stack that started each one. Recorded requests don't go through Cloak Proxy, so rules, breakpoints and Map Remote don't apply to them. Use a capturing browser for that.
- **Safari:** not available. (added in Cloak Proxy 0.5.0) Safari's extensions can't attach to a tab's network activity or choose a proxy per tab, so the popup explains this instead of showing **Record This Tab**. To capture Safari, turn on [macOS capture](https://docs.subcloak.com/cloak-proxy/capture/macos-traffic/); with the extension on, its requests are tagged with their tab.
- **Firefox:** that tab's requests go through Cloak Proxy, so they're captured like any proxied traffic and rules apply. Firefox needs to trust Cloak Proxy's certificate for HTTPS. The capturing browser sets that up, or see [Certificate](https://docs.subcloak.com/cloak-proxy/capture/certificate/).

Click **Stop Recording** in the popup, or close the tab, to stop.

## Console errors

The extension forwards uncaught exceptions and rejected promises from every tab it's allowed on, and, while a tab is being recorded in Chrome, `console.error` and `console.warn` calls and the browser's own errors (failed CSP checks, mixed content). The **Browser Extension** sheet shows the latest. [Report Bug](https://docs.subcloak.com/cloak-proxy/sessions/report-bug/) adds the ones from a minute before the first request to a minute after the last to its summary, under **Browser console**, and attaches all of them as `browser-console.json`. **Clear** empties the list.

## Safari

(added in Cloak Proxy 0.5.0)

From 0.5.0 the Safari extension is built from the same files as the others, so it looks and pairs the same. Safari's extension APIs allow less:

| | Safari | Chrome, Edge, Brave | Firefox |
|---|---|---|---|
| Tag requests with the tab, frame and what started them | Yes (the resource type, such as `script`) | Yes | Yes |
| The page that made the request | No | Yes | Yes |
| Console errors (uncaught exceptions, rejected promises) | Yes | Yes | Yes |
| Record This Tab, with stacks and response bodies | No | Yes | Yes, through Cloak Proxy (no stacks or bodies) |

In the **Browser** tab, a request from Safari shows the browser (**Safari**), the tab's title and URL, the frame, and what started it as a resource type, such as `script`. Safari doesn't tell extensions which page made a request, so there's no page URL.

Safari reports a request only when the extension is allowed on the website that made it. Allow it on every website (step 4 of the Safari [install](#install) steps), or the **Browser** tab stays empty for sites you haven't allowed. The popup shows an orange note when access is missing. In 0.5.0 the note can stay visible after you've allowed every website; that's a known issue, and tagging still works.

Safari may connect directly to a page served from your Mac's own network address (for example `http://192.168.1.20:3000`) instead of going through the proxy, so those requests aren't captured or tagged. Websites on the internet go through Cloak Proxy as usual.

*[Screenshot: The Browser Extension sheet with a Safari row marked Off and an Open Safari Settings button, the Chrome, Edge, Brave and Firefox instructions, a Pair button, and Safari extension and Chrome extension under Paired browsers, both Connected. The Browser Extension sheet in 0.5.0, with Safari paired next to Chrome.]*

If **Proxy › Browser Extension…** says Safari doesn't list the extension yet, move Cloak Proxy to the Applications folder, open it from there, then quit and reopen Safari.

## For assistants

Through the [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/):

- `browser_extension_status`: the paired browsers, tabs being recorded and how many console errors were collected. From 0.5.0 also `safari`: whether the app includes the Safari extension and whether it's on (`on`, `off`, `not-found` or `not-included`). (added in Cloak Proxy 0.5.0)
- `get_browser_context`: where a request came from in the browser (tab, page, frame, script, stack).
- `list_browser_console`: the latest console errors and warnings, with their tab, script, line and stack.

`list_flows` and `cloakctl query` take `tab:` like the query bar.

## Privacy

The extension sends requests' URLs and methods, tab titles and URLs, and console messages to Cloak Proxy on this computer only. Recording a tab in Chrome also sends that tab's request and response bodies. Nothing is stored in the browser except the port, the key and the tagging switch. Cloak Proxy keeps the contexts with the requests in memory, like the requests themselves, and the console messages until you clear them or quit.

## Related

  - [Capturing browser](https://docs.subcloak.com/cloak-proxy/devices/capturing-browser/): Open Chrome or Firefox already set up to use Cloak Proxy.
  - [Report Bug](https://docs.subcloak.com/cloak-proxy/sessions/report-bug/): Bundle failing requests, console errors and a recording.
  - [Query language](https://docs.subcloak.com/cloak-proxy/inspect/query-language/): Filter by tab, status, duration and more.