How to use Charles Proxy in 2025

If you‚ ever wanted to peer behind the scenes of your network traffic, Charles is a great place to start. It‚ has a secure proxy tool used by developers, QA teams, and anyone who wants to inspect HTTP/HTTPS interactions

In this article, you‚ will learn how to install Charles, how to set it up for various projects, and how to make the most of its debugging features.

Let‚ us jump in.

1. Installing Charles

First things first: you need to get Charles installed on your machine.

Go to the official Charles website and download the version compatible with your operating system.

Follow the standard installation steps.

Once installed, open Charles.

You‚ will see a main window with a large, empty area where your traffic will appear. On the left, you have a structure or hierarchy of hosts. You‚ will typically see something like:

└── Local Machine
    ├── localhost
    ├── example.com
    └── ...

But for now, it will be empty until you begin real traffic inspection.

2. Starting a Session

Whenever you open Charles, it starts in a default recorded session. If you want to be more organized:

Go to File > New Session.
Choose a meaningful session name.
Once you hit OK, Charles starts recording network requests.

Browsers and other applications route traffic through Charles if you configure your system‚ has proxy settings. By default, Charles does a lot of this automatically, especially on macOS. Windows users might need to confirm a few settings to trust the Charles certificate and enable SSL proxying.

3. Configuring SSL Proxying

HTTPS traffic is encrypted. That means you can’t read it as plain text.
But with Charles, you can use SSL proxying to decrypt this data for debugging.

Steps to enable SSL proxying:

1. Go to Proxy > SSL Proxying Settings.
2. Click Add.
3. Enter the host domain you‚ are interested in, e.g. *.example.com.
4. Or simply use * (asterisk) to capture all domains, though this is less secure.

After that, you need to install the Charles Root Certificate.

By trusting this certificate, your system allows Charles to act as a man-in-the-middle and decrypt your traffic.

Example on macOS:
• Go to Charles > Help > SSL Proxying > Install Charles Root Certificate.
• This opens the Keychain Access.
• Add the certificate and set Trust to Always.

4. Testing HTTP Requests

Once SSL proxying is configured, open your browser.

Navigate to a test site, e.g. https://example.com.

Watch the Charles main panel populate with requests.

You‚ will notice each resource in your panel. Something like:

GET / HTTP/1.1
Host: example.com

Highlight a request. Look at the Request tab vs. the Response tab in the bottom panel.

The Request tab shows headers, query params, and more.

The Response tab shows the returned data, like HTML or JSON.

5. Breakpoints for Deeper Debugging

One of the best features of Charles is the ability to use breakpoints.

A breakpoint lets you pause a request or response before it continues.

How to add a breakpoint:

1. Right-click on a request in the main window.
2. Select Breakpoints > Add.

Or you can configure a breakpoint in Tools > Breakpoint Settings.

When a matching request or response occurs, Charles halts the flow. A pop-up window appears, letting you modify the data on the fly.

Imagine debugging a login flow. You can intercept a request, change the header, test different states, or even simulate server errors by editing the response. This is especially helpful when testing edge cases.

Code Example:

Editing JSON on the Fly

Suppose you paused an API call returning JSON user data:

{
  "username": "alice",
  "role": "user"
}

You can switch to the ‚ audit Response‚ in tab. Adjust the JSON as follows:

{
  "username": "alice",
  "role": "admin"
}

Click Execute or Forward, and your app sees the updated role. This helps QA teams check how the app deals with admin privileges, for instance.

6. Using Rewrite Rules

Sometimes, you just want to rewrite requests automatically. That‚ is where Rewrite Rules are your friend.

Go to Tools > Rewrite.
Enable Rewrite.
Click Add to create a new set of rules.

You can match hostnames, methods, and paths. Then define the rewrite you want. For example, if you want to redirect all species commands to a mock JSON endpoint:

• Type: Modify Query Param or Replace Host
• Match: Host = api.example.com
• Replace with: local.mockserver.dev

Remember to enable the rule. Check the main Charles window to watch your requests get rerouted behind the scenes.

7. Mapping Local Files

Another handy feature is Map Local. This is perfect when you want your local environment to serve certain files instead of the production server. You can override scripts, images, or entire JSON feeds with local versions.

Steps to do so:

1. Go to Tools > Map Local.
2. Click Add.
3. Select the remote source (like https://example.com/app.js).
4. Map it to a local file (like file:///Users/me/project/app.dev.js).

Now, every time your app attempts to get https://example.com/app.js, it receives your local file instead. No more messing with hidden dev mode settings or complicated server rewrites. Charles handles it seamlessly.

8. Reverse Proxies for Mobile Testing

Need to debug an iOS or Android client? Charles can help.

Install the Root Certificate on your mobile device.

Point your device‚ Wi-Fi proxy settings to the IP address and port that Charles is using (your laptop or desktop).

Now you can see and debug the traffic from your phone apps. If SSL runs, just trust the certificate to read traffic inline. This is invaluable for diagnosing slow or failing requests in mobile apps.

9. Performance Analysis

You can also get a sense of performance.

Check the Timeline view.

Requests are laid out horizontally across time.

Look for bottlenecks or slow responses. If an endpoint is timing out, it‚ will show a long bar. By correlating the timeline with the Sequence view, you can pinpoint exactly which resource is misbehaving.

10. Exporting Sessions and Sharing

Once you‚ recorded your session, you can stop the capture.

Then go to File > Save Session As.
Export the Charles session as a .chls or .chls.zip file.

This is super useful if you‚ are collaborating with a team. Let‚Äôs say you found a bug and want your devs to see how it happened. Just share the .chls file, and they can open it in their own Charles session. They‚Äôll see exactly what you saw.

11. Debugging Different Environments

If you have dev, staging, and production URLs, Charles is a huge help.

Use Map Host or Map Remote to switch traffic between these environments without changing code.

Similarly, you can create multiple rewrite sets, enabling them or disabling them as you move from one environment to another.

12. Troubleshooting Common Pitfalls

Sometimes you‚ will see empty requests or weird SSL errors. Double-check you‚ have installed and trusted Charles‚ in certificate.

Ensure your firewall or antivirus is not blocking Charles.

On macOS these days, you might need to allow permissions in System Settings > Network if the automatic proxy config fails.

13. Scripting with Charles

Charles also provides a Scripting feature using JavaScript.
Automate tasks like rewriting URLs or processing sessions.
For instance, you can strip out specific request headers every time.

Sample Script

(function (event) {
  var request = event.getRequest();
  request.removeHeader("If-Modified-Since");
  // The next line logs the removal to the Charles event console
  event.console.log("Stripped out If-Modified-Since header");
})

14. A Quick Recap

1. You install Charles.
2. You enable SSL proxying.
3. You watch traffic flow.
4. You add breakpoints to intercept.
5. You rewrite or map local files for advanced debugging.
6. You export or share sessions to collaborate.
7. You script or automate as needed.

Charles is continually updated with features that make debugging simpler for web and mobile developers alike. Once you‚ are comfortable with the basics, you can employ advanced tactics like rewriting cookie values or simulating slow network speeds.

Final Thoughts

Charles is a powerful companion tool for web and app development.
Whether you‚ are tracking down elusive bugs, rewriting requests to test scenarios, or analyzing performance, Charles gives you eyes on the network level.

Because you can intercept SSL traffic, debug mobile apps, and manipulate flows in real time, you end up with fewer guesswork-laden debugging sessions. Instead, you rely on direct evidence from your captured logs and breakpoints.

Now that you know how to install, configure SSL, break open requests, and rewrite traffic with Charles, you are poised to uncover the secrets behind any network request.

That means faster debugging, more accurate fixes, and a deeper understanding of how your data moves across the web.

Time to open Charles.

You‚ have got a network to debug.