Proxyman has established itself as a high-performance, native macOS application designed to replace legacy web debugging proxies like Charles Proxy and Wireshark for modern development workflows. Its architecture, powered by SwiftNIO—a cross-platform asynchronous event-driven network application framework developed by Apple—delivers superior performance on Apple M1, M2, M3, and M4 silicon. While the application excels at capturing HTTP/HTTPS, WebSocket (WS/WSS), and gRPC traffic through its Atlantis framework, the handling of gRPC specifically presents a nuanced landscape for developers. The platform does not officially support native gRPC protobuf parsing, which creates specific limitations in how binary protocol buffer payloads are rendered and inspected. This distinction is critical for teams relying on gRPC for microservice communication, as it dictates the tools and workarounds necessary for effective debugging.
The Atlantis Framework and Traffic Capture
At the core of Proxyman’s ability to intercept and inspect network traffic is the Atlantis framework. This component is responsible for capturing HTTP/HTTPS, WS/WSS, and gRPC traffic across various environments, including iOS physical devices, iOS simulators, Android physical devices, and Android emulators. The framework operates as a reverse proxy and supports network throttling, allowing developers to simulate poor network conditions to test application resilience.
For gRPC specifically, the Atlantis framework can capture the raw traffic streams. However, because Proxyman does not officially support the decoding of the gRPC protobuf format, the captured data is not automatically parsed into human-readable structures. This means that while the connection and the gRPC transport layer are visible, the application-layer payload remains in its binary or base64-encoded form unless external tools or manual interpretation are applied. This limitation is documented in official issue trackers, noting that the Protobuf feature cannot parse gRPC data properly due to the lack of native protobuf support.
The impact of this limitation is significant for teams using gRPC extensively. Unlike HTTP/JSON, which is inherently readable, gRPC relies on Protocol Buffers for serialization. Without native parsing, developers must rely on the raw hex view or export the data for external processing. This workflow adds friction to the debugging process, contrasting with the streamlined experience Proxyman offers for standard RESTful APIs.
Interoperability and Stability Challenges
Despite the architectural strength of the Atlantis framework, real-world usage of Proxyman for gRPC traffic has revealed intermittent stability issues. Reports from development teams indicate that gRPC requests sometimes fail to appear in the Proxyman interface, even when the application on the simulator or physical device reports success. This discrepancy suggests that the traffic is being processed but not correctly surfaced or logged by the proxy tool.
Troubleshooting these visibility issues often involves restarting both Proxyman and the target application, though this is not a consistent fix. Disabling the "macOS proxy overridden" setting has also been reported as a potential workaround, albeit a flaky one. The presence of the Atlantis framework itself has been questioned in these scenarios, with users uncertain if the framework contributes to the instability.
The following table outlines the observed symptoms and attempted resolutions for gRPC visibility issues in Proxyman:
- Symptom: gRPC requests fail to show up in Proxyman despite successful execution on the device.
- Environment: iOS Simulator and iOS Physical Device.
- Attempted Fix 1: Restarting Proxyman and the running application.
- Effectiveness: Intermittent; sometimes resolves the issue, but not always.
- Attempted Fix 2: Disabling "macOS proxy overridden."
- Effectiveness: Flaky; provides temporary relief but is not a reliable solution.
- Potential Factor: Usage of the Atlantis framework may impact stability, though the exact causal relationship remains unclear.
These issues highlight the complexity of debugging binary protocols like gRPC through a proxy tool primarily optimized for HTTP/HTTPS. The lack of native protobuf support exacerbates these stability concerns, as developers cannot easily verify if the data was captured but merely rendered incorrectly.
Scripting as a Workaround for Data Manipulation
To mitigate the limitations of native parsing and to enhance debugging capabilities, Proxyman provides a robust JavaScript scripting engine. This feature is designed to replace the ReWrite tool found in Charles Proxy, offering greater flexibility and power. Developers can write JavaScript code to manipulate requests and responses on the fly, implement Map Local and Map Remote rules, and set breakpoints for dynamic inspection.
The scripting engine supports a wide range of operations, including modifying request content such as domain, host, scheme, port, path, HTTP method, headers, query parameters, and body data (whether encoded-form, JSON, or plain-text). Similarly, response content can be altered, including HTTP status codes, headers, and body data in various formats. The engine includes built-in addons and libraries for common tasks such as hashing, encoding/decoding, JSON/text transformation, and beautification.
In recent updates, specifically version 6.10.0 released in May 2026, the scripting capabilities were enhanced to support npm-style require(...) syntax. This allows developers to install and use third-party libraries via the npm install command, significantly expanding the potential for complex data transformation. While this does not directly solve the native gRPC protobuf parsing issue, it enables developers to write custom scripts that might decode or transform binary data using external libraries, provided the library is compatible with the Node.js runtime environment used by Proxyman.
javascript
require('some-grpc-decoder-lib');
The ability to assign and receive shared states between scripts or current sessions using ShareState or environment variables further enhances the flexibility of this approach. Developers can create complex debugging pipelines that preprocess gRPC traffic, potentially converting binary payloads into a more readable format before they are displayed in the UI.
Platform Integration and User Experience
Proxyman is distinguished by its native macOS implementation, adhering strictly to macOS Human Interface Guidelines. This native approach ensures super-fast performance on Apple Silicon and provides a familiar user interface with universal shortcut keys, reducing the learning curve for developers. The application includes a comprehensive suite of networking debugging tools, including Breakpoint, Map Local, Scripting, and Map Remote, all refined for ease of use in 2026+ design standards.
For mobile development, Proxyman offers detailed certificate guidelines for iOS, Android, simulators, and emulators. Configuration on remote devices, often a tedious process, is streamlined with single-click setup options for iOS physical devices, iOS simulators, Android physical devices, and Android emulators. Additionally, Proxyman for iOS is a native iOS app that allows developers to capture HTTP/HTTPS traffic directly from iOS devices without requiring a Mac, though this feature requires iOS 16 or later.
The application supports multiple filters with various criteria, allowing users to instantly search requests by URL, regex, method, header, body, and more. Requests can be pinned and saved in folders for later inspection, facilitating organized debugging sessions. These features, while not specific to gRPC, contribute to an overall efficient debugging environment that compensates for the lack of native protobuf parsing by providing powerful tools for data manipulation and organization.
Conclusion
Proxyman remains a leading choice for web debugging on macOS, offering superior performance and a modern user interface compared to legacy tools like Charles Proxy. However, its handling of gRPC traffic is constrained by the lack of native protobuf support, which prevents the automatic parsing of binary protocol buffer payloads. This limitation, combined with intermittent stability issues in capturing gRPC requests through the Atlantis framework, requires developers to adopt workarounds such as custom JavaScript scripting or external data processing. The recent introduction of npm-style library support in the scripting engine offers a pathway for developers to extend Proxyman’s capabilities, potentially mitigating some of these limitations. For teams heavily reliant on gRPC, understanding these constraints and leveraging Proxyman’s scripting and filtering tools is essential for effective debugging.