Charles Proxy — What It Is, Setup and Intercepting HTTPS Traffic

What Is Charles Proxy?

Charles Proxy is an HTTP proxy and HTTP monitor that acts as an intermediary between the client and the server. All requests and responses pass through Charles, allowing you to view their contents, analyze structure, modify data in real time, and simulate various network conditions. It is available for Windows, macOS, and Linux.

History and Positioning

Charles Proxy was created in 2004 by Karl von Randow and remains one of the most popular tools for debugging network traffic. Unlike free alternatives, Charles offers a paid license with a 30-day trial period. The tool is positioned as a professional solution for mobile app developers, web developers, and QA engineers who need full control over HTTP communications.

Platform Compatibility

Charles operates as a system proxy on your computer and can intercept traffic from any devices on the same network: Android, iOS, simulators, emulators, web browsers, and IoT devices. To intercept HTTPS, you need to install the Charles root certificate on each device. Traffic is supported on HTTP/1.1 and HTTP/2 (partial). HTTP/3 (QUIC) is not supported at the interception level.

How Charles Proxy Works

Charles operates on the principle of an MITM (Man-in-the-Middle) proxy: when a client sends a request through Charles, the tool intercepts the request, forwards it to the target server, receives the response, and passes it back to the client. All traffic passes through Charles, allowing it to be analyzed and modified.

Proxy Architecture

When launched, Charles creates a local HTTP proxy on port 8888 (default). The operating system or application is configured to use this proxy. All HTTP requests are sent to Charles first, which then acts as a full client to the target server. For HTTPS, Charles uses its own SSL proxying technique: it generates a certificate on the fly for each domain, signed by the Charles root certificate. If the root certificate is installed on the device as trusted, Charles can decrypt and view HTTPS traffic.

Operating Modes

Charles supports two modes: Proxy (classic proxy server) and SOCKS Proxy (for UDP and TCP traffic). Standard HTTP-proxy is used for web development. For mobile devices — configure WiFi Proxy on the device pointing to the IP address of the computer running Charles. macOS supports automatic proxy configuration for the iOS simulator.

<!-- Configuring network_security_config.xml for Android with Charles support -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <!-- Trust Charles certificate in Debug build -->
            <certificates src="user" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Key Features of Charles Proxy

Charles Proxy provides a set of professional tools for analyzing and modifying traffic that go far beyond simple request interception.

Rewrite and Breakpoints

The Rewrite tool allows you to automatically change certain parts of requests or responses: headers, URL parameters, response body. For example, you can replace the User-Agent header with a value from another device or remove certain cookies. Breakpoints work like a debugger: the request stops at a selected stage (before sending or before receiving), and the developer can manually change its contents before it proceeds further. This is useful for testing handling of error responses or non-standard states.

Map Local and Map Remote

Map Local allows you to replace a network resource (CSS, JS, JSON) with a local file from disk. This is indispensable in frontend development: you can modify CSS/JS and see the result immediately without deploying to a server. Map Remote redirects requests from one URL to another — for example, from a production server to staging for testing. Both tools work with URL patterns supporting wildcards.

Throttle and Network Condition Simulation

The Throttle tool allows you to simulate various types of network connections using preset profiles: 3G, EDGE, GPRS, DSL, WiFi. You can configure speed limits (download/upload), latency, packet loss, and stability. This is critical for testing application behavior under slow or unstable connections — proper timeout handling, retry logic, offline mode.

Auto Save and Recording

Charles can automatically save traffic sessions to .chls files, allowing you to analyze them later or share with colleagues. Recording Control lets you flexibly configure which traffic to save: by domain, content type, or status code. This is convenient for long-term API monitoring.

Setting Up Charles Proxy for Mobile Devices

For debugging mobile app traffic, Charles is configured as a WiFi Proxy: all devices on the same network as the computer can route traffic through Charles. Correct HTTPS configuration requires installing the Charles certificate on the mobile device.

Setup on Android

For Android: open Settings → WiFi → Advanced → Proxy, select Manual, and enter the computer's IP address with port 8888. Then open a browser on the device and go to http://chls.pro/ssl to download the Charles certificate. On Android 7+ (API 24+), a network_security_config.xml is required to trust user certificates in Debug builds — otherwise the app may not route traffic through Charles.

Setup on iOS

For iOS: Settings → WiFi → configure proxy with IP and port 8888. Then Safari → http://chls.pro/ssl → install the certificate profile. On iOS 10.3+, you must additionally enable certificate trust: Settings → General → About → Certificate Trust Settings → enable Charles Proxy. iOS is stricter about certificates: some apps may use SSL Pinning, blocking traffic through Charles even with a trusted certificate.

Solving SSL Pinning Issues

If the app uses SSL Pinning (server certificate pinning), standard proxying through Charles will not work — the app will reject the Charles certificate. Solutions: disable SSL Pinning in Debug builds via OkHttp or URLSession settings, use Frida to bypass pinning at runtime, or use Android Emulator with root access.

Practical Use Cases for Charles Proxy

Charles Proxy solves specific development and testing tasks. Let's look at the most common scenarios where the tool is indispensable.

Debugging API Integration

The most common scenario — checking the correctness of API requests. Charles shows the exact request URL, headers, body, and parameters. If the server returns an unexpected response, you immediately see: JSON structure, error code, response headers. This lets you distinguish client-side errors from server-side errors without logs from both sides.

Testing with Slow Connection

Using Throttle profiles, you can test how the app behaves under low connection speed: whether a loading indicator is displayed, whether timeouts are handled correctly, whether the UI freezes on connection loss. It is especially important to test caching — if data has already been loaded, the app should show it from cache rather than entering an infinite loading state.

Editing Server Responses

Using Breakpoints, you can modify the server response before it is sent to the app. For example, return an empty array instead of data, change the status code to 500, add a new field to JSON. This allows you to test edge case handling without modifying server code — one of the most powerful uses of Charles in mobile development.