Debugging an iPhone from a Mac

This guide goes from a phone with Chute installed to a Mac window showing that phone's decrypted requests, with the request and response bodies, ready to filter and export. It strings together things that have their own reference pages — the CA, the host list, recording, the control channel, Dashboard — in the order you actually do them, and says at each step what you should be seeing before you go on.

You need:

• Chute iOS on the phone, with a license. HTTPS decryption and body capture are licensed on iPhone; without a license everything below still connects, but HTTPS rows stay opaque and the data tabs cannot be selected. See License and Activation.
• Chute Dashboard on the Mac — free, no license.
• A USB cable (recommended: nothing to open on the network, and it works on cellular), or the phone and the Mac on the same Wi-Fi.

If you would rather not install anything on the Mac, the Web Console shows the same connections, bodies and rewrites in a browser, and needs only external-http-controller on the phone. Steps 1–3 below apply to it unchanged; from step 4 on, follow Opening the web console instead.

1. Install and trust the CA

On the phone, in the configuration editor: MITM → Configure CA → Generate A New CA Certificate, then Install CA Certificate to System, then trust it under Settings → General → About → Certificate Trust Settings. The full walk-through, including the step everyone misses, is on the HTTPS decryption page.

You should see: the certificate page reads Trusted CA Certificate. If it reads Not Trusted, the trust switch in Certificate Trust Settings is still off — nothing later will work until it is on.

2. Say which hosts to decrypt

Chute decrypts only the hosts you list. In the editor's MitM section (the one with Configure CA), add the hosts you want to look at. Start narrow — the API host of the app you are debugging — rather than *: every decrypted host costs CPU on the phone, and some apps pin their certificates and break when decrypted. *.apple.com is best excluded from the start.

[MITM]
enable = true
hostname = api.example.com, *.example.net, -*.apple.com

The grammar — ports, - exclusions, /path scoping — is on the HTTPS decryption page. You can also add and remove hosts later from Dashboard's MitM Rules panel while watching the effect, and copy the ones that work into the configuration.

3. Turn on decryption and recording

On the phone's Control Panel, two switches:

• MitM — decryption on, for the hosts from step 2.
• Traffic Capture — record request and response bodies (the replica setting). Without it Dashboard shows every connection with its rule and policy, but no data.

Both can also be flipped later from Dashboard's toolbar, so it is not a problem if you forget them now. Neither survives a restart unless it is in the configuration (replica = true in [General], enable = true in [MITM]), and on iPhone both are licensed features that the engine refuses without a license whatever the configuration says.

4. Let Dashboard connect

In the configuration editor: External Controller.

1. Turn on External Controller Access — its footnote reads Allow Chute Dashboard/Chute CLI to Connect.
2. Enter a Port (any free port; 6170 if you have no preference) and a Password of your own.
3. Allow Access From Wi-Fi: leave it off for USB. Turn it on only if you will connect over Wi-Fi — it opens the listener to everyone on that network who has the password.
4. Save, and start (or restart) the tunnel.

You should see: the Control Panel shows External Access Port: 6170 (your port). If the line is missing, the tunnel is not running the saved configuration — restart it.

5. Connect Dashboard

Plug the phone into the Mac and, if asked on the phone, Trust this computer. Open Chute Dashboard; in the New Dashboard window choose Connect via USB, pick the phone under Device:, enter the Port from step 4 and the Password, then connect.

Over Wi-Fi instead: Connect to Remote Machine, with Host = the phone's address (Settings → Wi-Fi → ⓘ, IP Address), and the same port and password.

You should see: a new Dashboard window, its Active list filling as the phone makes connections. Use the phone for a few seconds if it is empty. Two things can go wrong here: Password does not match, and a phone that cannot be reached (wrong address, Wi-Fi access off, tunnel not running) — the window opens all the same, and over Wi-Fi it ends in Connection Closed, while over USB it stays on Connecting…, retrying until the phone answers. The Dashboard page has the details.

6. Check the toolbar switches

At the top of the Active list, the two switches from step 3 as Dashboard sees them:

• Traffic Capture should read Disable Traffic Capture — recording is on. If it reads Enable Traffic Capture, click it.
• Enable MitM (N rules) should read Disable MitM (N rules) — decryption is on, and N is the number of hosts from step 2. If the button carries no (N rules) count, the host list did not reach the phone: check step 2 and restart the tunnel.

7. Reproduce and find the request

Do the thing in the app whose traffic you want. Then narrow the list with the filter bar above it: type the host into Filter Host/URL… — the toolbar's Filter field is the same search — or tick MitM Only to keep just the decrypted rows.

You should see: rows for your host with an M in the Flags column. The Method column shows the connection type — HTTPS — not the verb: the request line and the status line are the first rows of Req Hdr and Resp Hdr. Select one: the Req Hdr tab has the headers, query parameters and cookies; Resp Data shows the body, as Text until you pick JSON for a tree or Image for a picture.

If the rows for your host have no M, the connection was not decrypted. In order of likelihood: the host is not in the list (or the pattern does not match — api.example.com does not cover www.example.com); MitM is off; the CA is installed but not trusted (the app itself will be showing certificate errors); the app pins its certificate (exclude the host and accept that you cannot see inside); the app talks HTTP/3 over QUIC, which cannot be decrypted — set block-quic to steer it back to TCP.

If the row has M but Req Data and Resp Data cannot be selected, nothing was captured: recording was off when that connection ran (turn it on, reproduce again), or the host is filtered out by [Replica] on the phone. A body larger than 2 MiB is one the phone declines to hand over; its tab reads Unable to load this body.

8. Keep what you found

Select the rows and right-click one of them: Export Selected as HAR… writes all of them, with their bodies, to a file that opens in a browser's developer tools, Charles or Proxyman; Copy curl Command copies the clicked row's request, to repeat it from the Mac's terminal; Export Selected as CSV… for a spreadsheet. Export as bin inside a data tab saves one body as captured.

9. Change something (optional)

The MitM view's panels edit the running engine. Two quick experiments:

• Header Rewrite → add a rule for your host: Request, Add, X-Debug = 1. Reproduce; the new rows carry H and R, and the detail panel's Rules Fired quotes your rule.
• Mock Response → answer an endpoint with a body of your own. The Response Body type is a pop-up — file, text, base64 or tiny-gif — and the box beside it takes what the type needs: a path for file (Browse… picks one), the body itself for text, its base64 for base64, and nothing for tiny-gif. A file path is read by the phone, which has no /Users/…, so for a phone pick text or base64 and put the body in the rule itself, right here in the panel — see the note under MitM Tools. Mocked rows carry K.

Rules added here disappear when the tunnel restarts. Once one works, write it into the configuration — the reference pages: URL Rewrite, Header Rewrite, Body Rewrite, Mock Response.

When you are done

• Turn Traffic Capture off, or set replica = false: bodies accumulate on the phone for as long as recording is on.
• Turn Allow Access From Wi-Fi off again if you turned it on.
• Leave the CA installed if you will do this again; otherwise remove it under Settings → General → VPN & Device Management.