13/11/2019 Browser & System Configuration • Charles Web Debugging Proxy

Skip to content →

Charles
Web Debugging Proxy Application for Windows, Mac OS and Linux

Home
Overview
Documentation
Download
Buy
Support

Welcome
Installation
Getting Started
Configuration
Browser & System Configuration
Preferences
Recording Settings
Proxy Settings
Access Control
External Proxies
HTTP 1.1

Using Charles
Proxying
Tools
FAQs
Additional Information
Version History
Security
Privacy Statement
Charles for iOS

Download
Download a free trial
Version 4.5.4

Sketch version control & design workflow management. Sign your team up for free.ads via Carbon

Browser & System Configuration

In order for any browser (or any application) to use Charles it must be configured to use Charles as its proxy server. Most browsers will have a way to
configure this manually, but configuring manually is annoying because you have to configure and reconfigure everytime you start and stop Charles.

Fortunately Charles can autoconfigure the proxy settings in many cases including:

Windows / Internet Explorer proxy settings – used automatically by most Windows applications
macOS proxy settings – used automatically by most macOS applications
Mozilla Firefox proxy settings (all platforms)

Windows Proxy Settings

Charles can automatically configure the Windows proxy settings so that Internet Explorer and other Windows applications automatically start using
Charles. By default Charles will configure and then reconfigure the Windows proxy settings whenever Charles is started or quit.

Charles proxy configuration behaviour can be changed in Charles in the Proxy Menu, Proxy Settings dialog.

The Windows proxy settings are configured in the Internet Options control panel on the Connections tab if you want to look at them yourself.

Microsoft Edge has an additional setting that you may need to make by browsing to about:flags and enabling Allow localhost loopback. This is required in
order to connect to Charles Proxy running on localhost.

macOS Proxy Settings

Charles can automatically configure the macOS system proxy settings so that Safari and other macOS applications automatically start using Charles.

When you first install Charles you will be prompted to grant permissions to Charles to autoconfigure the proxy settings. After that, Charles will configure
and then reconfigure the macOS proxy settings whenever Charles is started or quit.
https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/ 1/3
13/11/2019 Browser & System Configuration • Charles Web Debugging Proxy
Charles proxy configuration behaviour can be changed in Charles in the Proxy Menu, Proxy Settings dialog.

The macOS proxy settings are configured in the advanced areas of the Network panel in the System Preferences if you want to look at them yourself.

In order to use HTTP 2 with Charles from Safari you must use Charles in SOCKS mode. See the Proxy Settings for configuring SOCKS.

iOS Device Settings

To use Charles as your HTTP proxy on your iPhone you must manually configure the HTTP Proxy settings on your WiFi network in your iPhone's
Settings.

Go to the Settings app, tap Wi-Fi, find the network you are connected to and then tap it to configure the network. Scroll down to the HTTP Proxy setting,
tap Manual. Enter the IP address of your computer running Charles in the Server field, and the port Charles is running on in the Port field (usually 8888).
Leave Authentication set to Off.

All of your web traffic from your iPhone will now be sent via Charles. You should see a prompt in Charles when you first make a connection from the
iPhone, asking you to allow the traffic. Allow this connection. The IP address of your iPhone will be added to the Access Control list in Charles, which you
can view and change in the Proxy menu > Access Control Settings.

Remember to disable the HTTP Proxy in your Settings when you stop using Charles, otherwise you'll get confusing network failures in your applications!

Auto configuration

You can also supply an auto-configuration URL instead of entering manual configuration. This approach will enable your device to first try to use Charles,
but then to fallback to using a direct connection if Charles isn't running. This is an experimental approach!

For the auto-configuration URL enter:

https://chls.pro/X.X.X.X.pac

Where you replace X.X.X.X with the IP address of your computer running Charles. This defaults to port 8888. If you use a different port, just include that,
e.g. https://chls.pro/X.X.X.X:XXXX.pac

You can also use Charles in SOCKS proxy mode from iOS using an autoconfiguration rule, in spite of this not being available as a manual setting. Enter
the auto-configuration URL as follows:

https://chls.pro/X.X.X.X:XXXX.socks.pac

HTTP 2

Safari on iOS 10 does not currently support HTTP 2 via HTTP proxies. In order to use HTTP 2 with Safari on iOS and Charles Proxy you need to use
Charles in SOCKS mode and use the auto-configuration URL described above to specify SOCKS mode.

iOS Simulators
The iOS Simulator should use the system proxy settings. If it doesn't, please try quitting and restarting the iOS Simulator. As of Xcode 6 it appears to be
important that Charles is running and set as the macOS system proxy before you run the iOS Simulator.

Mozilla Firefox Proxy Settings

Configure Firefox to use your system proxy settings. In Firefox, go to Preferences > Advanced > Network > Connection Mozilla Firefox can now be
configured to use the system proxy settings, which is usually preferable as Charles can control the system proxy settings on Windows and macOS
without the need for installing an add-on. Check your Firefox proxy settings in Preferences > Advanced > Network > Connection and press the Settings
button. Then choose "Use system proxy settings".

Manual Proxy Configuration

In Charles, go to the Proxy menu and choose Proxy Settings. This will show you the currently configured HTTP Proxy Port and SOCKS Proxy Port. Note
down which one you want to use (probably HTTP Proxy).

The host name is 127.0.0.1 (your own computer) or the external address of your computer if you want to access Charles from another computer.

You can then configure your browser or application’s proxy settings with that host name and port.

Java Application Proxy Configuration

You can configure your Java application to use Charles in code or as command line arguments to the java executable.

System.setProperty("http.proxyHost", "127.0.0.1");
System.setProperty("http.proxyPort", "8888");

And for HTTPS as well. Note that you may also want to configure Java to trust Charles’s root certificate in this case (see SSL Proxying).

System.setProperty("https.proxyHost", "127.0.0.1");
System.setProperty("https.proxyPort", "8888");

For the source of this information, including more discussion and how to set these as command line arguments:
http://java.sun.com/j2se/1.5.0/docs/guide/net/proxies.html

See this tutorial on integrating Charles with your Java application by a Charles user. Or see this tutorial on integrating Charles with the Play framework.

cURL and libcurl

For cURL on the command line:
curl --proxy localhost:8888

https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/ 2/3
13/11/2019 Browser & System Configuration • Charles Web Debugging Proxy
If you are developing an application using libcurl you can configure it to use Charles as its proxy server:

curl_easy_setopt(pCurl, CURLOPT_PROXY, "127.0.0.1");

curl_easy_setopt(pCurl, CURLOPT_PROXYPORT, 8888);

If you are using SSL you may like to disable the certificate verification during development, if you can’t get cURL to trust Charles’s CA certificate:

curl_easy_setopt(pCurl, CURLOPT_SSL_VERIFYPEER, 0);

Thanks to Michael Klische for providing this information.

Android emulator
In the Android emulator run configuration add an Additional Emulator Command Line Option:
-http-proxy http://LOCAL_IP:8888

Where LOCAL_IP is the IP address of your computer, not 127.0.0.1 as that is the IP address of the emulated phone.

Android
Some Android devices have HTTP proxy settings. On the Nexus S it is hidden; you can access the HTTP proxy settings by opening the Voice Dialler app
and saying "proxy". On some Samsung devices you can access proxy settings by long-pressing on the network name in the WiFi configuration.

You can also hardcode your application to use a proxy server during testing:

HttpHost httpproxy = new HttpHost("192.168.0.101", 8888, "http");

httpClient.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY,httpproxy);

or

HttpUrlConnection conn = url.openConnection(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("192.168.0.101", 8888)));

Make sure the first IP address is the IP address of your computer running Charles, then add this code to customise your httpClient or to open a URL
connection.

Charles is developed by XK72. All content is copyright 2019. Site design by Matthew Buchanan.

https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/ 3/3