Mastering Proxyman for HTTP and HTTPS Debugging

You've shipped a feature, and something is subtly wrong with how your app talks to the API. The UI looks fine. The backend logs show nothing. But somewhere between the client request and the server response, data is going sideways — and console.log isn't going to find it for you. What you need is to see the actual traffic.

Proxyman is a modern, native HTTP and HTTPS debugging proxy that lets you intercept, inspect, and modify every network request passing through your development environment. Running natively on macOS and iOS, it gives developers and QA engineers full visibility into HTTP and HTTPS traffic in real time — including the encrypted HTTPS traffic that most other tools make frustratingly difficult to decode. It's the kind of tool that, once you've used it seriously, makes you wonder how you debugged APIs without it. In this guide, we'll cover exactly what Proxyman is, how its HTTPS interception works, how to set it up and start capturing traffic, and the most important techniques for getting real value out of it in your daily debugging workflow.

By the end, you'll have a practical foundation for using Proxyman as your primary network debugging tool — from basic traffic inspection to request rewriting and API testing.

What Is Proxyman?

Proxyman is a native macOS application — with companion support for iOS, iOS Simulator, and Android — that acts as a man-in-the-middle proxy between your application and the network. Every HTTP and HTTPS request your app makes passes through Proxyman's proxy server, where it can be captured, decoded, inspected, replayed, and modified before it reaches its destination.

The primary use case is network debugging: when you need to see exactly what your app is sending and receiving, Proxyman gives you that visibility at the request and response level, with headers, bodies, query parameters, status codes, timing data, and everything else in between. This is invaluable for API inspection — verifying that your client is constructing requests correctly, confirming that the server is returning what it claims to return, catching encoding issues, debugging authentication flows, and diagnosing timing problems that only appear in real network conditions.

Where Proxyman distinguishes itself from older tools in the same space — Charles Proxy, Fiddler, Wireshark — is in the quality of its native macOS design. It's built for macOS using native UI frameworks, which means it feels like a first-class Mac application rather than a Java port from another era. The interface is fast, readable, and thoughtfully organized for the workflows developers actually use. According to Proxyman's official documentation (https://docs.proxyman.io), the tool supports macOS, iOS physical devices, iOS Simulator, and Android, with automatic setup scripts that handle the system proxy configuration steps that are traditionally tedious to get right.

For QA engineers running API test suites, the ability to see — and modify — live traffic between a test client and a backend transforms what's possible during a test session. For backend engineers debugging production-like environments locally, Proxyman makes the network layer as observable as any other part of the stack.

How Proxyman Works: HTTPS Interception Under the Hood

Understanding how Proxyman captures HTTPS traffic is worth a few minutes of your time — because if you've ever tried to debug encrypted traffic and gotten nothing but unintelligible ciphertext, you'll appreciate why Proxyman's approach works when naive approaches don't.

HTTPS traffic is encrypted using TLS. The encryption is established between the client (your app) and the server, and no party in between — including your local proxy — can read the content without breaking or bypassing that encryption. This is, of course, exactly what TLS is designed to guarantee. So how does Proxyman see inside encrypted requests?

It uses a technique called TLS interception, sometimes called SSL bumping. Here's how it works. Proxyman generates its own Certificate Authority (CA) certificate and installs it in your system's trusted certificate store. When your app makes an HTTPS request, it actually connects to Proxyman's proxy server, not directly to the destination. Proxyman presents a dynamically generated certificate for the target domain, signed by its own CA. Because your system trusts Proxyman's CA, your app trusts this certificate and completes the TLS handshake with Proxyman. Proxyman then makes a separate TLS connection to the actual destination server on your behalf, reads the plaintext response, passes it to you, and logs the entire exchange in cleartext.

From the app's perspective, the connection looks secure and valid. From Proxyman's perspective, it's reading everything. This is a man-in-the-middle architecture by design — and it's exactly what makes it useful for debugging. The critical point: this only works because you explicitly installed Proxyman's CA certificate and trusted it on your own machine. No one else can intercept your traffic this way without physical access to your device and your explicit trust configuration. As the Mozilla documentation on TLS explains, the trust chain in TLS is what determines who can establish valid encrypted connections — and Proxyman inserts itself into that chain on your local development machine under your own control.

For iOS physical devices, an additional step is required: you install the CA certificate on the device via a configuration profile and explicitly enable trust for it in iOS Settings. Proxyman automates much of this through its setup assistant, but it's worth understanding why that step exists.

Step-by-Step Guide: Setting Up and Using Proxyman

Step 1: Install Proxyman and Configure the System Proxy

Download Proxyman from https://proxyman.io or via Homebrew:

brew install --cask proxyman

On first launch, Proxyman will prompt you to install its CA certificate into your macOS System Keychain and set itself as the system HTTP/HTTPS proxy. Follow the setup prompts — both steps are necessary for full traffic capture. Proxyman automates most of this, but you'll need to enter your system password to authorize the keychain and proxy changes.

Once set up, Proxyman listens on localhost:9090 by default. Any application configured to use the system proxy — browsers, most API clients, and many macOS apps — will route traffic through Proxyman automatically.

Step 2: Trust the Proxyman CA Certificate

After installation, you need to explicitly trust Proxyman's CA certificate before HTTPS traffic decryption will work. In Proxyman, navigate to Certificate → Install Certificate on this Mac and follow the prompts. In Keychain Access, find the Proxyman CA certificate, open it, expand the Trust section, and set "When using this certificate" to "Always Trust."

Without this step, Proxyman captures the fact that HTTPS traffic occurred but cannot decrypt its content — you'll see the connections but get empty request and response bodies for all HTTPS traffic.

Step 3: Start Capturing Traffic

With the proxy configured and the certificate trusted, Proxyman begins capturing traffic automatically when you use your browser or any proxy-aware application. Click the record button in Proxyman's toolbar to begin a capture session. Open your target application, trigger the network activity you want to inspect, and watch requests appear in Proxyman's traffic panel in real time.

Each request in the list shows the method, URL, status code, content type, and timing at a glance. Click any entry to open the detail view — request headers, request body, response headers, and response body, all decoded and readable. For JSON API responses, Proxyman renders the body with syntax highlighting and collapsible tree structure. For binary content, it shows a hex representation. For form-encoded bodies, it parses the key-value pairs.

Step 4: Use Filters to Find What You Need

In a busy development environment, your traffic panel will fill up quickly with requests from browsers, background processes, system services, and your actual target application all mixed together. Proxyman's filtering system is how you stay focused.

The quickest filter: click on any domain in the traffic list and select "Only show this domain" from the context menu. Proxyman scopes the view to that domain instantly. For more persistent filtering, use the Filter bar at the top of the traffic panel — you can filter by domain, path, method, status code, or any combination. Save frequently used filters for workflows you run repeatedly.

Step 5: Modify and Replay Requests

This is where Proxyman moves from a passive observer to an active debugging tool. Two features are particularly powerful here.

Breakpoints let you pause a request or response mid-flight and edit its content before it continues. Set a breakpoint on a specific URL pattern, trigger the request in your app, and Proxyman pauses the traffic and opens an editor where you can modify headers, body content, or query parameters before releasing it. This is invaluable for testing how your app handles modified API responses, edge case status codes, or malformed payloads — without modifying your backend at all.

Rewrite Rules let you define persistent modifications that apply automatically to matching traffic. Redirect a production API endpoint to a local development server, strip or add headers, replace response bodies with fixture data, inject delays to simulate slow network conditions. Rewrite rules persist across sessions and apply to all matching requests without intervention.

Step 6: Debug iOS and Physical Device Traffic

To capture traffic from an iOS physical device, connect the device to the same Wi-Fi network as your Mac. In Proxyman, go to Certificate → Install Certificate on iOS and follow the instructions to install the CA profile on the device. In iOS Settings, navigate to General → VPN & Device Management, trust the Proxyman profile, then go to General → About → Certificate Trust Settings and enable full trust for the Proxyman CA.

Set your iOS device's Wi-Fi proxy settings to Manual, pointing to your Mac's local IP address on port 9090. From that point, all HTTP and HTTPS traffic from the device routes through Proxyman on your Mac. For iOS Simulator, Proxyman provides an automated setup script that handles configuration without manual proxy settings.

Common Challenges and Limitations

Certificate pinning blocks HTTPS interception. Some apps implement certificate pinning — hardcoding the expected server certificate or public key into the app itself, so that any certificate not matching the pinned value is rejected, including Proxyman's dynamically generated certificates. Apps that use certificate pinning will fail their network requests when Proxyman tries to intercept them. Bypassing pinning requires either a modified build of the app with pinning disabled, a jailbroken device running a pinning-bypass tool, or working directly with your engineering team to configure a debug build without pinning. This is a known limitation of all TLS interception proxies, not specific to Proxyman.

Non-proxy-aware applications won't be captured. Proxyman captures traffic from applications that respect the macOS system proxy setting. Some applications — particularly those built with custom networking stacks or those that hardcode direct connections — ignore the system proxy entirely, meaning their traffic won't appear in Proxyman regardless of your configuration. For those cases, network-level capture tools like Wireshark or packet sniffers operate below the proxy layer and can capture all traffic regardless of application behavior.

The CA certificate must be re-trusted after macOS updates. Major macOS updates occasionally reset certificate trust settings, which means Proxyman's CA certificate may require re-trusting after a system update. If HTTPS traffic suddenly stops decrypting after an OS update, re-running the certificate installation and trust steps is the first thing to check.

Traffic volume can make manual inspection difficult. In a complex application with many background network calls, finding the specific request you care about in a high-volume session takes deliberate use of Proxyman's filter and search tools. Building a habit of starting a fresh capture session focused on a specific workflow — rather than leaving capture running indefinitely — keeps the traffic panel manageable and makes individual request inspection faster.

Android setup is more manual than macOS and iOS. Proxyman's Android support requires manually configuring the device's Wi-Fi proxy settings and installing the CA certificate through the device settings — there's no automated setup script equivalent to the iOS assistant. On Android 7 and above, apps that target API level 24 or higher also don't trust user-installed CA certificates by default for encrypted connections, which can require a debug build with a network security configuration that explicitly permits user CAs.

Conclusion

Proxyman earns its place as a primary network debugging tool for macOS developers by doing the hard parts well: HTTPS interception that actually works, a native interface that doesn't get in your way, and a feature set — breakpoints, rewrite rules, filtering, multi-platform capture — that covers real debugging workflows rather than just passive observation.

The learning curve is real but short. Getting the CA certificate installed correctly and understanding why HTTPS interception requires it are the two conceptual hurdles; everything after that is building familiarity with the interface. Most developers who spend a day with Proxyman in a real debugging session find it becomes a permanent fixture in their toolkit. Start with a simple capture session on a familiar API, work through the filtering and inspection features, then explore breakpoints when you hit a bug that passive inspection alone won't solve. That's the path from installed to genuinely useful.

What We Learned

Proxyman is a native macOS HTTP and HTTPS debugging proxy: It intercepts, decodes, and displays network traffic from applications in real time, giving developers and QA engineers full visibility into what's actually being sent and received.
HTTPS interception works through trusted CA certificate injection: Proxyman inserts itself into the TLS trust chain by generating its own CA and installing it in your system keychain — understanding this explains both why it works and what its limits are.
Breakpoints and rewrite rules transform passive inspection into active debugging: The ability to pause, modify, and replay live traffic — or to apply persistent rewrite rules automatically — is what makes Proxyman more than a logging tool.
Certificate pinning is the most common blocker for HTTPS interception: Apps that hardcode expected certificates reject Proxyman's interceptions; working around this requires a debug build or pinning-bypass configuration.
Filters and focused capture sessions are essential in high-volume environments: A disciplined capture workflow — filtering by domain, scoping sessions to specific features — is as important as the tool itself for productive debugging.
iOS Simulator setup is automated; physical devices and Android require manual steps: Know the setup requirements for each target platform before you need them in the middle of a debugging session.

FAQ

What is Proxyman used for?

Proxyman is a network debugging proxy used to intercept and inspect HTTP and HTTPS traffic between applications and servers. Developers use it to debug API integrations, verify request and response content, test how apps handle modified or error responses, and diagnose network-layer issues that aren't visible at the code or log level. It's particularly useful for mobile app development, where the network layer between a client app and a backend API is often the hardest part of the stack to observe directly.
How does Proxyman decrypt HTTPS traffic?

Proxyman decrypts HTTPS traffic using a technique called TLS interception. It installs its own Certificate Authority (CA) certificate into your system's trusted certificate store. When your app makes an HTTPS request, it connects to Proxyman first, which presents a dynamically generated certificate for the target domain signed by its own CA. Because your system trusts Proxyman's CA, your app completes the TLS handshake with Proxyman, which can then read the plaintext traffic before forwarding it to the real destination over a separate TLS connection.
Is Proxyman safe to use for development?

Yes, for local development and debugging purposes. Proxyman's CA certificate operates only within your trusted certificate store on your own device — it doesn't affect connections on any other machine and is under your direct control. The standard precaution is to remove or distrust the CA certificate in production or shared environments where you don't want HTTPS interception active. Never install development proxy CA certificates on production devices.
Can Proxyman capture traffic from iOS apps?

Yes. Proxyman captures traffic from iOS physical devices and iOS Simulator. For physical devices, you install Proxyman's CA profile on the device, enable trust in iOS Settings, and configure the device's Wi-Fi proxy to point to your Mac. For iOS Simulator, Proxyman provides an automated setup script that handles configuration without manual proxy settings. For apps with certificate pinning enabled, additional steps — typically a debug build with pinning disabled — are required before interception will work.
What is the difference between Proxyman and Charles Proxy?

Both are HTTPS debugging proxies that work through TLS interception, and both serve the same core use case. The main practical difference is the development experience: Proxyman is built natively for macOS and feels like a first-class macOS application, while Charles Proxy is a Java-based application that runs cross-platform (macOS, Windows, Linux) with an interface that reflects its older design heritage. Proxyman tends to be faster to interact with and easier to set up on macOS; Charles has broader platform coverage. For macOS-first development teams, Proxyman is generally the preferred modern option.
Why is some HTTPS traffic not decrypted in Proxyman?

If HTTPS traffic appears in Proxyman's panel but shows empty or encrypted request and response bodies, the most common causes are: the Proxyman CA certificate isn't fully trusted in Keychain Access (check that trust is set to "Always Trust," not just "Use System Defaults"), the application implements certificate pinning (which rejects Proxyman's intercepted certificates), or the application uses a networking stack that bypasses the system proxy. Re-running Proxyman's certificate installation flow and verifying Keychain trust settings resolves the first case; the other two require different approaches specific to the application.