Network Debugging
Chute is a proxy, but the reason to run one on your own devices is usually not routing. It is that every request now passes through a place you control — so you can watch what an app actually sends, keep the bodies and read them afterwards, change a request or a response while it is in flight, and make a healthy backend look broken to see what your app does about it.
The reference pages for each mechanism are elsewhere in this manual: HTTPS Decryption, Mock Response, URL Rewrite, JS Scripting. This section puts them in the order you actually use them, and says what changes from platform to platform.
Four surfaces onto the same engine
One running Chute; four ways to look at it. Picking the wrong one is the usual reason something "isn't there".
| Runs on | Request and response bodies | Changes the running engine | Needs | |
|---|---|---|---|---|
| The app itself | The device | iOS and Android yes; macOS and tvOS no | The switches only — Chute Mac also saves them to the configuration file | Nothing |
| Web Console | A browser, any device | Yes | MitM hosts, every rewrite family, policies, configuration | external-http-controller |
| Chute Dashboard | A Mac | Yes | MitM hosts, every rewrite family, the two switches | Nothing for Chute Mac on that same Mac; external-controller-access for any other device |
| HTTP Control API | Anything that speaks HTTP | Yes, base64 | Everything the console can | external-http-controller |
The console and Dashboard overlap heavily and are reached differently — the console is served by the engine and opened in a browser, Dashboard is a Mac application talking a binary channel. Neither is a superset of the other; What Dashboard cannot reach lists the differences.
Four switches to get right first
Nearly every "I see the connection but not the request" ends at one of these four, in this order:
- The traffic reaches Chute at all. A row in the traffic view is the proof. Nothing at all is a takeover problem, not a debugging one — see Troubleshooting.
- The CA is installed and trusted. Two separate steps on iOS, one on macOS, and neither of them on tvOS — see Installing and trusting the CA certificate.
- The host is on the MitM list. Chute decrypts declared hosts and nothing else. In Dashboard, a row without the
Mflag was never decrypted. - Recording is on.
replica = true, or the switch (Traffic Capture in the app). On iPhone, Apple TV and Android the engine also requires a license, so the key alone captures nothing there. Without recording every row still carries its rule, policy and timings — only the payloads are missing.[Replica]then narrows what is kept, and what is kept lasts only as long as the run: Chute deletes the recorded bodies when it stops.
Switches 3 and 4 are also togglable at runtime from the console, from Dashboard and over the API, and none of those writes anything back to the configuration file: after a restart the file wins.
What each platform gives you
| Chute iOS | Chute Mac | Chute tvOS | Chute Android | |
|---|---|---|---|---|
| Inspect in the app | Dashboard screen — Overview, Request, Response, with bodies | Traffic tab — routing, no bodies | DIAGNOSIS → Dashboard — routing, no bodies | Dashboard — Tunnels, with bodies |
| Toggle MitM in the app | Control Panel switch (licensed) | Menu bar → Enable MitM (⌘M) | No switch on this platform | Control Panel → MitM (licensed) |
| Toggle recording in the app | Control Panel → Traffic Capture (licensed) | Menu bar → Traffic Capture (⌘B) | Control Panel → Traffic Capture (licensed) | Control Panel → Traffic Capture (licensed) |
| Install the CA | In the app, then trust it in Settings | In the app, one step | MDM or Apple Configurator only | Import P12 in the app, then Install CA opens Android's installer |
| Chute Dashboard reaches it | USB cable or Wi-Fi | Connect to Local Machine, on that Mac | Wi-Fi | USB cable (adb) or the network |
| Get a file off the device | Share sheet | The file system | The console, by QR code | Share sheet |
Where to go from here
- Debugging an iPhone from a Mac — the whole path end to end, from a fresh phone to a decrypted body on a Mac screen.
- Debugging on a Mac — the Mac's own traffic, including terminal tools and per-process isolation.
- Debugging an Apple TV — a device with no browser, no share sheet, and no way to install a certificate by itself.
- Replica — which connections keep their bodies, and how to stop capturing everything.
- Mocking and Fault Injection — canned responses, error statuses, injected latency, and what Chute genuinely cannot simulate.
When the answer is "it doesn't work" rather than "what is it doing", start at Troubleshooting instead — in particular Why doesn't my rewrite do anything?, which is the question this section produces most often.