Skip to content →

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
  • Mac OS X proxy settings – used automatically by most Mac OS X 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.

Mac OS X Proxy Settings

Charles can automatically configure the Mac OS X system proxy settings so that Safari and other Mac OS X 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 Mac OS X 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 Mac OS X proxy settings are configured in the Network panel in the System Preferences if you want to look at them yourself.

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!

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 Mac OS X system proxy before you run the iOS Simulator.

Mozilla Firefox Proxy Settings

Mozilla Firefox proxy settings are configured automatically using a Firefox Add-On. Download the add-on.

The Charles Autoconfiguration Add-on adds a Charles option in the Tools menu in Firefox; you can view the current status in that menu. However you will not usually need to use that menu as the add-on will silently take care of configuring and unconfiguring Firefox.

When you first install Charles, it will check for and prompt you to install the Firefox add-on. If you don’t install the Firefox add-on immediately you will later need to enable Firefox configuration in the Proxy Settings in the Proxy menu.

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

Also see this tutorial on integrating Charles with your Java application by a Charles user.

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://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".

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);

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