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.
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
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://10.0.2.2:8888
Where 10.0.2.2 is a special IP address for Android Emulators that resolves to the host computer IP. If you run Charles on another computer, replace that IP address with the IP address of the other computer.
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.