Debugging on a Mac

On a Mac, Chute and the traffic you want to look at are on the same machine, so most of what the iPhone guide spends steps on — a cable, a listener, a password — is not needed. What replaces it is a different question: is the traffic reaching Chute at all, because on macOS an application can simply decline to use the proxy.

1. Make the traffic go through Chute

Two mechanisms, and they are independent — the menu shows both:

• System Proxy — the toggle at the top of the menu. Registers Chute as the system HTTP/SOCKS proxy. Applications that read the system proxy settings (browsers, most GUI apps) go through Chute; ones that do not are unaffected.
• Enhanced Mode (⌘E) — captures traffic at the network layer, so an application's opinion about proxies stops mattering. This is what you want when an app has no proxy support at all. See Enhanced Mode for the approval flow and the two implementation types.

Terminal tools are the usual surprise: curl, git, npm and friends read HTTP_PROXY/HTTPS_PROXY from the environment, not the system settings. The menu's Copy Shell Export Command (⌘C) puts the right line on the clipboard —

export HTTPS_PROXY=http://127.0.0.1:8118;export HTTP_PROXY=http://127.0.0.1:8118;export NO_PROXY=127.0.0.1,localhost,.example.com

— with your actual HTTP listener port and a NO_PROXY built from your skip-proxy list, so command-line tools bypass exactly what the system proxy bypasses. Paste it into the shell you are testing from; it applies to that shell only.

You should see: the main window's Traffic tab filling with rows as you use the app. (The main window is Open Dashboard... (⌘,) in the menu; on a Mac that already had configurations before the current interface, turn on Use New Main UI there first.) No rows means the traffic never reached Chute — go back to this step rather than looking for a decryption problem.

2. Read the Traffic tab

Traffic lists live connections with a search field and a count (N active). Show columns ▾ switches the layout:

• Double-row (the default) — two lines per connection, comfortable for browsing.
• Wide table — one row per connection across all columns: Host, Process, Rule, Policy, Proto, Upload, Download, Totals, State. Sortable by clicking a header.
• Group by app — connections collected under the application that opened them, with its name and icon. This is the fastest way to answer "what is this process talking to".

Right-click a row for Show Details, Copy Host, Copy Details, Filter Logs (jumps to the Log tab already filtered to this connection) and Close Connection.

Show Details opens a window with the connection's Host, Process, Protocol, Remote, Rule, Policy, Rewrites, Upload, Download and State — everything about how it was routed.

The Traffic tab does not show request and response bodies. That is what the detail window's Requests & History button is for: it opens the Web Console, which does. The console's home page opens, not that particular connection.

3. Test a rule without making a request

The Rules tab has a Test Rule… button. Type a URL or a bare domain, press Test, and Chute answers with the host and port it parsed, the DNS result, the matched rule, the policy that rule chose, and any notes.

Use it whenever the question is "why did this go direct" or "which of my two rules wins" — it consults the running rule set, so it also tells you whether the configuration you edited is actually the one that is loaded. Reload the configuration (⌘R) if the answer looks stale. The same question over the API is POST /api/rules/match.

4. Turn on recording and decryption

Both live in the menu, and both act on the running engine:

• Traffic Capture (⌘B) — keeps request and response bodies, i.e. the replica setting. Off by default; nothing has bodies until it is on.
• Enable MitM (⌘M) — turns on decryption for the hosts in the [MITM] hostname list.

Both are written back to the configuration file — replica, and enable under [MITM] — so they outlast a reload and a restart. A remote configuration has no local file to write to: the switch still changes the running engine, and the app reports Failed to Save Configuration. The console, Dashboard and the API switch the same two settings without writing the file; after such a switch, Reload Configuration (⌘R) keeps what you set unless the file changed underneath — replica is re-applied when its own value in the file changed, [MITM] enable when any key of the [MITM] section did or the host list was edited from the console or the API — and a restart starts from the file.

The CA is a single step on macOS. In the configuration window open MitM:

1. Generate New Certificate, or Import Certificate from PKCS#12 File.
2. Install the Certificate to System — macOS asks for an administrator password and adds it to the System keychain as a trusted root. There is no separate "trust" step as there is on iOS.
3. Export the Certificate writes a .pem copy, which is how you get the same CA onto a phone, an Apple TV or a container.

5. Narrow to one process

Of the Apple platforms, macOS is the one where Chute knows which application opened a connection, and rules can use it (Chute Android knows it too, by package name):

[Rule]
PROCESS-NAME,curl,DIRECT
PROCESS-NAME,MyApp,MyProxy

See Process Rule for PROCESS-NAME, PROCESS-PATH and PROCESS-NAME-REGEX. Combined with Group by app in the Traffic tab, this lets you route one application through a proxy — or through a mock — while everything else on the machine carries on normally.

6. What only works on a Mac

• data= file paths in Mock Response rules. The file is read by the device running Chute, at request time. On a Mac that device is the machine you are editing on, so a real path works, and editing the file changes the next response with no reload. On a phone the same path means nothing — that is why the iPhone guide uses base64= instead.
• The files on disk. Log shards and the connection database live under ~/Chute/Share/<run id>/, and the run marker beside them in ~/Chute/Share/; see File Locations (macOS). You can attach them to a bug report directly instead of going through a share sheet. Captured bodies are there too, under DUMP/, but only while the engine runs: stopping it deletes them, so export what you need first — Export HAR in the console, or Export as bin in Dashboard.
• Serving other devices. With allow-wifi-access on, other machines on the network can point their proxy settings at this Mac. Their traffic then appears in the same views, under Remote in Dashboard's client sidebar — which is how you inspect a device Chute does not run on at all, a Windows laptop or a smart TV included.

7. When the Traffic tab is not enough

• Web Console — menu bar → Open Web Console. Bodies, HAR export, the Rules page that says which rewrites have fired, and the Diagnostics probes. Needs external-http-controller in [General].
• Chute Dashboard — a separate free app. On this Mac it needs no configuration at all: the menu's Open Chute Dashboard... (⌘D) opens it already connected to this Mac, and in its New Dashboard window Connect to Local Machine does the same. That route reaches the engine over a local socket the tunnel always opens, so there is no port and no password to set. Only when Dashboard runs on a different Mac do you need the remote route — external-controller-access = <password>@0.0.0.0:6170 in [General], then Connect to Remote Machine with this Mac's address, that port and that password. Worth it either way for the MitM tool panels and the HAR/curl exports on a right-click.
• The Log tab — raise the level with loglevel = verbose first, and revert afterwards. Filter Logs on a connection row narrows the tab to that one connection.