Debug a mobile app

Your iPhone app makes a call that fails, and the Xcode console only shows a status code. This guide captures the app’s HTTPS traffic on your Mac, decrypts it, finds the failing request, resends it with a fix, and pauses it mid-flight so you can change it before it reaches the server. It finishes by removing the proxy and certificate from the device.

What you need

An iPhone or iPad on the same Wi-Fi network as your Mac	The device sends its traffic to Cloak Proxy over the network
Cloak Proxy running, with the certificate trusted on this Mac	See Install and the certificate page
An app you own or are authorized to debug	Decrypting someone else’s traffic without permission is off limits

Caution

Only decrypt traffic from apps and devices you own, or that you have written permission to test. The Cloak Proxy certificate lets your Mac read the device’s HTTPS, so treat it like a key: remove it from the device when you’re done.

Let the device connect

By default Cloak Proxy listens only on 127.0.0.1, so other devices can’t reach it. Turn that on first.

1. Open Settings → Network (or Settings → General) and turn on Allow other devices to connect (phones, other computers).

   The Devices window’s iPhone & iPad tab also has an Allow Other Devices to Connect button that does the same thing.

2. Note This Mac’s address shown below the toggle, for example 192.168.1.20, and the port (9090 by default).

   123

   Turn on Allow other devices to connect, then apply and restart the proxy.

   1. Listening port (9090 by default)
   2. Allow other devices to connect
   3. Apply & Restart Proxy after changing it

   ×

   

Caution

While Allow other devices to connect is on, anyone on your network can use the proxy. Turn it off when you finish device debugging. To restrict it, add your device’s IP under Allowed devices in Network settings — this Mac is always allowed.

Point the device at Cloak Proxy and trust the certificate

Open the Devices window (the Devices toolbar button) and choose iPhone & iPad.

1234

The iPhone & iPad tab: Wi-Fi proxy, then the certificate.

1. Allow Other Devices to Connect, if not done yet
2. Wi-Fi proxy: your Mac's IP and port
3. Scan to open the certificate page
4. http://cloak.proxy also opens it in Safari

×

1. On the iPhone, open Settings → Wi-Fi, tap the ⓘ next to your network, then Configure Proxy → Manual. Enter your Mac’s address as the Server and 9090 as the Port.

2. Install the certificate. Scan the QR code in the Devices window with the iPhone camera, or open http://cloak.proxy in Safari on the device, and download the certificate.

   The certificate page is served by Cloak Proxy itself. On iOS, download the PEM profile.

3. On the iPhone, open Settings → General → VPN & Device Management and install the downloaded profile.

4. Turn on full trust: Settings → General → About → Certificate Trust Settings, and enable trust for Cloak Proxy CA.

Why full trust?

iOS installs the profile but won’t use the certificate for HTTPS until you enable full trust under Certificate Trust Settings. Without this step, the device’s HTTPS stays as locked tunnels.

Decrypt the app’s traffic

Use the app on the device. Its requests appear in the traffic list, grouped by app and domain in the sidebar. At first HTTPS shows as locked tunnels: Cloak Proxy relays them without reading them.

1. Select the app in the Apps section of the sidebar, or a request from it.

2. Click Enable SSL Proxying for All Requests in the bar above the table, or right-click the domain and choose Enable SSL Proxying for host.

   12

   A locked tunnel. Enabling SSL Proxying closes it so the app reconnects decrypted.

   1. Enable only this host
   2. Or every domain from this app

   ×

   

3. Enabling closes the open tunnels, so the app reconnects with decryption on. The next matching requests show method, URL, headers and bodies.

Note

SSL Proxying lists are kept in Settings → SSL Proxying. Use *.example.com to decrypt a whole domain, or * for everything from the app.

Find the failing call

1. Filter the list to the call you care about. Press <kbd>⌘</kbd> <kbd>F</kbd>, choose the field (URL, Host, Status Code, Response Body…) and a match mode, and type.

   1234

   The traffic list and inspector. The filter bar is at the top.

   1. Filter field and match mode (⌘F)
   2. Content chips: JSON, Form, GraphQL…
   3. Request and response tabs
   4. Response body, here a JSON tree

   ×

   

2. Click a failed request. A request that never reached the server shows No response with the reason (for example a DNS or TLS error).

   123

   A failed request: the reason is shown in both the header bar and the response pane.

   1. Failed, with timing
   2. The failure reason
   3. No response pane

   ×

   

3. Read the request and response tabs: Header, Query, Body, Cookies, Auth (JWT and Basic are decoded), and Raw. Use the response Body viewer’s Tree, Pretty, Raw or Hex modes.

Resend it with a fix

Once you see what’s wrong, change the request and send it again — through Cloak Proxy, so your tools still apply.

Edit & Repeat

Right-click the request and choose Edit and Repeat… (<kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>E</kbd>). The Compose window opens prefilled with the request. Change the method, URL, headers or body and press Send (<kbd>⌘</kbd> <kbd>↩</kbd>).

1234

Compose, prefilled by Edit and Repeat. Send goes through Cloak Proxy.

1. Method and URL
2. Send (⌘↩)
3. Import cURL to paste a command
4. Response appears below

×

Repeat

To resend it unchanged, right-click and choose Repeat (<kbd>⌘</kbd> <kbd>R</kbd>). The result appears in the list as a new request.

The resent request shows up in the main window under the app Cloak Proxy (Compose).

Pause it at a breakpoint

To change a request or its response while the app is waiting, set a breakpoint. The app stalls until you decide.

1. Right-click the request and choose Tools → Breakpoint…, or open Tools → Breakpoint and add a rule. Creating it from a request fills in the matcher and turns the tool on.

   123

   A breakpoint rule. Pause on the request, the response, or both.

   1. Tool on/off
   2. Matcher: method, URL, wildcard or regex
   3. Pause on request and/or response

   ×

   

2. Make the device repeat the call. When it matches, the Breakpoint window opens and the status bar shows how many are paused.

   1234

   A paused request. Edit the method, URL, headers or body, then Execute.

   1. Request paused, with its rule
   2. Execute sends your edits
   3. Cancel sends the original
   4. Abort drops it

   ×

   

3. Edit the request and click Execute (<kbd>⌘</kbd> <kbd>↩</kbd>) to send your version, Cancel to send the original, or Abort to drop it.

4. If the rule also pauses the response, the window reopens when the response comes back. Change the status, headers or body (use Quick status for common codes) and Execute.

   123

   A paused response. Change the status, headers or body before the app receives it.

   1. Response paused
   2. Status code, with Quick status
   3. Format or Minify the JSON body

   ×

   

5. To release everything at once without edits, click Continue All.

Tip

Breakpoints stop the app from making progress until you act. Keep the rule’s matcher tight (one method and path), and turn the tool off when you’re done so other requests aren’t held.

Clean up

When you finish, undo the changes on the device and the Mac:

1. On the iPhone, remove the Wi-Fi proxy: Settings → Wi-Fi → ⓘ → Configure Proxy → Off.

2. Remove the profile: Settings → General → VPN & Device Management, select Cloak Proxy CA, and remove it.

3. On the Mac, turn off Breakpoint (and any other tool you enabled) in the Tools window or the Tools menu.

4. Turn off Allow other devices to connect in Settings → Network when you no longer need device access.

Note

The certificate on your Mac can stay for next time. To remove it entirely, use Remove from Keychain on the certificate settings page.

Related

iPhone and iPadThe full device setup reference, including the certificate page and QR code.

SSL ProxyingDecrypt by host, by app, with wildcards and pinned apps.

BreakpointEvery option for pausing and editing requests and responses.

Repeat, Edit & Repeat, ComposeResend and craft requests through the proxy.