Debugging tools

Debugging tools change traffic while it passes through Cloak Proxy. You can pause a request and edit it, answer it from a local file, send it to another server, rewrite it with JavaScript, slow it down, block it, or replay recorded responses offline. Use them to test how your app handles errors, edge cases and bad networks without changing the app or the server.

The tools

Cloak Proxy has eleven tools. Each one has its own rules and its own on/off switch.

Tool	What it does	Default
Breakpoint	Pauses matching requests or responses so you can edit them before they continue.	On
Map Local	Answers matching requests with a local file, folder, or a response you write. The server is never contacted.	On
Map Remote	Sends matching requests to a different scheme, host, port, path or query, such as staging instead of production.	On
Scripting	Changes requests and responses with JavaScript: onRequest and onResponse.	On
Block List	Blocks matching requests with a 403 or by dropping the connection.	On
Allow List	Only records matching requests. Everything else still works but isn’t shown.	Off
Network Conditions	Slows matching requests down to test 3G, high latency or packet loss.	Off
DNS Spoofing	Connects a host name to a different IP address while keeping the URL and Host header.	On
No Caching	Strips caching headers so every request reaches the server with fresh data.	Off
Mock Sets	Replays recorded responses without the network, so you can demo, test or debug an app offline.	On
Alerts	Posts a macOS notification when matching traffic fails, slows down or returns something specific.	On

A tool only does something when it’s on and has at least one enabled rule. No Caching has no rules: turning it on applies it to every request.

Which traffic tools can change

Tools work on HTTP requests that Cloak Proxy can read: plain HTTP, and HTTPS to hosts or apps with SSL Proxying on. Encrypted tunnels Cloak Proxy doesn’t decrypt, and WebSocket messages, pass through untouched. DNS Spoofing is the exception: it applies to every connection Cloak Proxy makes, including tunnels and WebSockets.

Open the Tools window

All rules live in the Debugging Tools window.

1. Choose Tools › Debugging Tools… or press ⌥ ⌘ 0.

   You can also click Tools (the wrench) in the main window’s toolbar and choose Debugging Tools….

2. Pick a tool in the sidebar on the left.

3. Add a rule with the + button at the bottom of the rule list, or with Add Rule when the list is empty.

4. Fill in the rule on the right. Changes apply right away; there’s no Save button.

Six tools also have their own shortcut in the Tools menu, which opens the window on that tool:

Menu item	Shortcut
Edit Breakpoint Rules…	⌥ ⌘ B
Edit Map Local Rules…	⌥ ⌘ L
Edit Map Remote Rules…	⌥ ⌘ M
Edit Scripting Rules…	⌥ ⌘ S
Edit Block List Rules…	⌥ ⌘ K
Edit Network Conditions Rules…	⌥ ⌘ T

The other tools have Edit … Rules… items in the same menu without a shortcut.

123456

The Debugging Tools window: tools on the left, rules in the middle, the selected rule's editor on the right.

1. Every tool. The icon is colored while the tool is on.
2. How many rules the tool has.
3. Green dot: the tool is on. Gray: off.
4. The tool's On/Off switch.
5. A rule. The checkbox turns just this rule on or off.
6. Add, delete and duplicate rules. Rules run top to bottom; drag to reorder.

×

Window layout

Area	What it shows
Sidebar (Debugging Tools)	Every tool with its icon, the number of rules it has, and a green (on) or gray (off) dot.
Header	The tool’s name, a one-line summary of what it does, and the On/Off switch.
Rule list	Each rule’s checkbox, name (or Untitled) and, under it, the method and URL it matches (or No URL yet). Right-click a rule for Duplicate and Delete.
Rule list buttons	+ adds a rule, − deletes the selected rule, and the third button duplicates it. The note Rules run top to bottom; drag to reorder is a reminder that order matters.
Editor	The selected rule’s settings. Every rule starts with a Rule section: a name and a matcher.

DNS Spoofing uses a table instead of a rule list, No Caching has only its switch, and Mock Sets lists recorded sets instead of rules. Their pages explain the differences.

Tip

A new rule has an empty URL and matches nothing until you fill it in. That makes it safe to add rules while traffic is flowing.

Turn tools on and off

Each tool has one switch that turns all its rules on or off at once. Its rules stay saved while it’s off. You can flip the switch in several places:

• The On/Off switch in the tool’s header in the Tools window.
• Tools menu: a checkmark item for every tool.
• The Tools toolbar button in the main window: the same list of toggles.
• Search Everything (⇧ ⌘ A): type the tool’s name and choose Turn On … or Turn Off ….

To pause a single rule, clear its checkbox in the rule list. A disabled rule is dimmed.

Rules and switches are saved and come back the next time you open Cloak Proxy.

Turn tools off when you're done

Rules keep working after you close the Tools window, and after you restart the app. A forgotten Map Local, Block List or Network Conditions rule can make a real app behave strangely later. Check the status bar for active tools before you move on.

See which tools are active

The status bar at the bottom of the main window shows a small chip for every tool that is on and has at least one enabled rule (and No Caching while it’s on). Click a chip to open that tool’s rules. When the window is narrow, the chips scroll sideways.

While a request or response is paused at a breakpoint, the status bar also shows an orange N paused at breakpoint button that opens the Breakpoint window.

See which tools changed a request

When a tool touches a request, the traffic list shows a colored badge before its path, with the tools separated by dots, for example Script · Map Remote. The labels are:

Badge	Added when
Block List	A Block List rule answered or dropped the request.
Network Conditions	A Network Conditions rule slowed or dropped it.
Script	At least one script ran on the request or response.
Breakpoint	The request or response paused at a breakpoint.
Map Local	Map Local answered the request.
Mock	A mock set answered it (with a recording or an offline 404).
Map Remote	Map Remote rewrote the URL.
No Caching	No Caching changed its headers.
DNS Spoofing	The host was connected to a spoofed address.

The traffic list records the request as it was finally sent, after every change.

Create rules from captured traffic

The quickest way to make a rule is from a request you already captured. Right-click a request in the traffic list and choose Tools, then a tool. Cloak Proxy creates a rule that matches that request, turns the tool on in most cases, and opens it in the Tools window. Rules and matching lists what each tool’s rule is prefilled with.

Share rules and use them elsewhere

• Tools › Export Rules… saves your rules to a JSON file, and Tools › Import Rules… adds rules from one. See Export and import rules.
• cloakctl run --tools RULES.json loads an exported file for headless and CI runs.
• The MCP server lets an AI assistant read and change rules with tools such as list_rules, upsert_rule, delete_rule, set_tool_enabled and rule_from_request, and resolve breakpoints with list_paused and resolve_paused. See the MCP tools reference.

How tools work together

When several tools match one request, they run in a fixed order: Block List first, then scripts and breakpoints, then Map Local, Mock Sets and Map Remote, then the server, then response scripts and breakpoints. The full order, and what each step can skip, is in Rule order and multiple tools.

Related

Rules and matchingWildcards, regex, methods, subpaths, the URL tester and rule order.

BreakpointPause and edit requests and responses.

Map LocalAnswer requests from local files or inline responses.

Mock a backendA guide that combines Map Local, Scripting and Mock Sets.