Simulator Proxy Setup

Quern can capture and display all HTTPS traffic from your iOS simulators. This is how you watch every API call your app makes in real time, without modifying your app’s code.

The Simple Version

Tell your agent:

“Set up network capture for my simulator and show me what API calls my app is making”

Your agent will make sure the proxy certificate is installed on the simulator, enable local capture for your app’s process, and start showing you traffic. That’s it for most workflows.

How Capture Works

Local Capture (The Default)

Local capture uses mitmproxy’s macOS System Extension to transparently intercept traffic from specific processes. Safari and WebKit networking are enabled by default (configured in ~/.quern/config.json). When you start debugging an app, ask your agent to add your app’s process name to the capture list.

Say add, and check what comes back. The web-view minimum (MobileSafari, com.apple.WebKit.Networking) is kept for you, so naming your app no longer loses page traffic — but everything else is set rather than merged, so an agent that sends only your app’s name still drops anything else you had. Quern reports what a change added and removed on the response (capture_added, capture_removed), and the CLI prints both. The server log carries removals only — an addition is not logged — so read the response rather than the log if you want to know what was kept for you. The request itself is valid either way, so nothing refuses it.

Why this is the right default:

• Your Mac’s browser and other apps are unaffected
• Nothing to clean up when you’re done
• Traffic from each simulator is automatically tagged so you can tell them apart

The first time local capture is used, macOS will ask you to approve the System Extension in System Settings > Privacy & Security. This is a one-time approval.

System Proxy (The Alternative)

If local capture isn’t working (System Extension issues, corporate MDM blocking it), your agent can fall back to the system proxy. This routes all Mac traffic through mitmproxy — including your browser. It works, but it’s messier.

Important: The system proxy must be turned off when you’re done. Your agent handles this, but if the server crashes or you kill it, your Mac’s proxy settings may be left configured. Run quern stop to clean up, or check System Settings > Network > your interface > Proxies.

Certificates

The proxy certificate needs to be installed on each simulator for HTTPS decryption to work. Without it, your agent can see that traffic is happening but can’t read the request/response bodies.

Quern checks for it before enabling capture, and asks before installing it. Capturing through a simulator that does not trust the certificate fails every HTTPS request from that device, and the symptom points nowhere near the proxy — a blank screen, or an app that seems to have no network — so Quern refuses to create that state rather than leaving you to discover it.

You are asked rather than having it done for you because installing a certificate authority is a bigger commitment than turning capture on: it persists across sessions, outlives the capture window, and you have to know it happened in order to undo it.

If you would rather answer once:

quern set-auto-install-cert on

That setting also appears in the Quern app’s Settings window, under Network capture, so it is visible and reversible from the same place. quern set-auto-install-cert with no argument prints the current setting.

The cert persists across app installs and simulator reboots — it’s only lost if you erase the simulator entirely. Quern asks the simulator itself every time rather than trusting what it recorded earlier, so an erase is noticed at once: erasing through Quern withdraws the trust claim as it happens, and an erase from anywhere else is caught by the next check. Either way you are asked again rather than left capturing traffic that cannot succeed.

Booting a simulator through Quern does not install the certificate on its own. Only enabling capture does, and only when auto_install_cert is on — otherwise you are asked. A root certificate authority installed as a side effect of booting a device is not something you would have been told about.

Per-Simulator Traffic Isolation

This is where Quern really shines for testing. When traffic flows through the proxy, Quern traces each request back to the specific simulator that made it. This means:

• Running the same app on three simulators? Traffic from each is labeled separately.
• Your agent can show you “just the traffic from the iPhone 15 Pro simulator” even when multiple simulators are active.
• Parallel test runners get isolated traffic views without any app-side changes.

This happens automatically — no configuration needed.

What You Should Know

Certificate Pinning

If your app uses certificate pinning (common in banking, healthcare, and security-sensitive apps), the proxy won’t be able to decrypt that traffic. Pinned apps explicitly reject mitmproxy’s certificate.

Solutions:

• Disable pinning in debug builds (most pinning libraries support this)
• Use a build configuration that skips pinning for development
• Accept that pinned traffic will appear as opaque HTTPS connections

What Gets Captured

Everything that goes through the network stack: REST API calls, GraphQL, WebSocket connections, image downloads, analytics pings, third-party SDK traffic. You’ll often discover surprising things your app (or its dependencies) are doing.

Performance Impact

Local capture adds minimal overhead — a few milliseconds per request for the TLS interception. You won’t notice it during normal development. System proxy mode has similar overhead but affects all traffic.

Troubleshooting

No traffic appearing:

• Ask your agent to check the proxy status. It reports every handshake a client refused — the host, which simulator and process refused it, and the TLS alert. That is the direct evidence, and it says which of the two causes below you have
• Make sure local capture includes your app’s process name. The web-view defaults are kept for you, but anything else you had named is replaced rather than merged
• Check if your app uses certificate pinning

Traffic appears but bodies are encrypted/empty:

• If the refusals say unknown ca, the cert isn’t installed or trusted. Ask your agent to reinstall it.
• Any other alert, on a simulator that does trust the CA, is usually the app pinning its certificate — reinstalling won’t help, and the fix is in the app’s build.

System Extension prompt not appearing:

• On macOS Ventura+, check System Settings > Privacy & Security > Network Extensions
• Corporate MDM policies may block System Extensions — fall back to system proxy mode