TL;DR

  • Charles Proxy intercepts HTTP/HTTPS traffic for inspection and modification
  • SSL Proxying requires certificate installation on device (mobile/browser)
  • Breakpoints let you modify requests/responses in real-time
  • Map Local/Remote redirects requests to local files or different servers
  • Throttling simulates slow networks for performance testing

Best for: Mobile testers, API developers, QA debugging production issues Skip if: You only need simple request inspection (browser DevTools is enough) Reading time: 14 minutes

The mobile app crashes but only on slow networks. The API returns different data in production than staging. You need to test error handling but can’t make the server return errors.

Charles Proxy sits between your app and the internet. It sees everything, lets you change anything. Network debugging becomes possible instead of guesswork.

This tutorial covers Charles from installation to advanced techniques — everything for effective network debugging.

What is Charles Proxy?

Charles Proxy is an HTTP proxy and monitor. It captures network traffic from any application configured to use it, displaying requests and responses for inspection.

What Charles does:

  • Intercept traffic — see every request your app makes
  • Inspect SSL/TLS — decrypt HTTPS for debugging
  • Modify requests — change headers, body, URL before sending
  • Mock responses — return fake data without server changes
  • Throttle bandwidth — simulate slow/unreliable networks
  • Record sessions — save and replay traffic for analysis

Common use cases:

  • Debug API integration issues
  • Test mobile apps without backend changes
  • Reproduce production bugs locally
  • Verify request/response formats
  • Test error handling with fake error responses

Installation and Setup

Installing Charles

macOS:

brew install --cask charles

Windows/Linux: Download from charlesproxy.com

Basic Configuration

  1. Launch Charles — it starts proxying immediately
  2. Go to Proxy → Proxy Settings
  3. Default port is 8888 (change if needed)
  4. Enable macOS Proxy or Windows Proxy for system-wide capture

SSL Proxying Setup

By default, Charles can’t read HTTPS content. Enable SSL Proxying:

  1. Go to Proxy → SSL Proxying Settings
  2. Check Enable SSL Proxying
  3. Add hosts: * for all, or specific like api.example.com
  4. Install Charles Root Certificate:
    • macOS: Help → SSL Proxying → Install Charles Root Certificate
    • Trust it in Keychain Access (Always Trust)
⚠️ Security Note: Only enable SSL Proxying for domains you're testing.
Never leave * enabled in production environments.

Browser Configuration

Chrome/Firefox Automatic

Charles automatically configures system proxy. Most browsers use it by default.

Manual Configuration

If automatic doesn’t work:

  1. Browser Settings → Network → Proxy
  2. Manual proxy: localhost:8888
  3. Use same for HTTP and HTTPS

Firefox Specific

Firefox uses its own proxy settings:

  1. Settings → Network Settings → Manual proxy
  2. HTTP Proxy: 127.0.0.1, Port: 8888
  3. Check “Also use this proxy for HTTPS”

Mobile Device Setup

iOS Configuration

  1. Connect iPhone to same WiFi as computer
  2. Find your computer’s IP: Help → Local IP Address
  3. On iPhone: Settings → WiFi → (i) next to network
  4. Configure Proxy → Manual
    • Server: your computer’s IP
    • Port: 8888
  5. Install SSL certificate:
    • Open Safari, go to chls.pro/ssl
    • Download and install profile
    • Settings → General → About → Certificate Trust Settings
    • Enable trust for Charles certificate

Android Configuration

  1. Connect to same WiFi
  2. WiFi Settings → Modify Network → Advanced
  3. Proxy: Manual
    • Hostname: computer’s IP
    • Port: 8888
  4. Install certificate:
    • Open browser, go to chls.pro/ssl
    • Download certificate
    • Settings → Security → Install from storage
    • For Android 7+: App must trust user certificates
// Android app network_security_config.xml for debugging
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="user" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Inspecting Traffic

Reading Requests

Click any request in Charles to see:

Overview Tab:

  • URL, method, status code
  • Timing information
  • Response size

Request Tab:

  • Headers (authentication, content-type)
  • Query parameters
  • Body (JSON, form data)

Response Tab:

  • Status code and headers
  • Body content (formatted JSON/XML)
  • Raw response data

Filtering Traffic

Focus on relevant requests:

  1. Sequence View: All traffic in order
  2. Structure View: Grouped by host
  3. Filter bar: Type domain to filter
  4. Focus: Right-click host → Focus (hides others)
  5. Exclude: Tools → Block List (hide noise)

Searching

Find specific content:

  • Cmd/Ctrl + F: Search in selected request
  • Edit → Find: Search all traffic
  • Search in headers, body, URL

Modifying Requests

Breakpoints

Stop requests for manual modification:

  1. Right-click request → Breakpoints
  2. Or Proxy → Breakpoint Settings for patterns
  3. When request hits breakpoint:
    • Modify URL, headers, body
    • Click Execute to continue
    • Click Abort to cancel
Pattern: https://api.example.com/users/*
Break on: Request and Response

Rewrite Tool

Automatic modifications without breakpoints:

  1. Tools → Rewrite
  2. Enable and add rule set
  3. Configure:
    • Location: api.example.com
    • Type: Modify Header / Body / URL
    • Match and Replace values

Example — Add auth header:

Type: Add Header
Where: Request
Header Name: Authorization
Header Value: Bearer test-token-123

Example — Modify response:

Type: Body
Where: Response
Match: "status": "pending"
Replace: "status": "completed"

Mocking Responses

Map Local

Return local file instead of server response:

  1. Right-click request → Map Local
  2. Select local file (JSON, HTML, etc.)
  3. All matching requests return your file

Use case: Test UI with specific data without backend changes

// mock-user.json
{
    "id": 1,
    "name": "Test User",
    "role": "admin",
    "features": ["beta-feature", "new-ui"]
}

Map Remote

Redirect requests to different server:

  1. Tools → Map Remote
  2. Map from: https://api.example.com/*
  3. Map to: https://staging.example.com/*

Use case: Test production app against staging backend

Compose New Request

Create requests from scratch:

  1. Tools → Compose
  2. Enter URL, method, headers, body
  3. Execute to send
  4. Useful for API exploration

Network Throttling

Simulate poor network conditions:

  1. Proxy → Throttle Settings
  2. Enable Throttling
  3. Choose preset or customize:
PresetBandwidthLatency
56k Modem48 kbps200ms
3G780 kbps200ms
4G8 Mbps50ms
CustomYour valuesYour values

Testing scenarios:

  • App behavior on slow connection
  • Timeout handling
  • Retry logic
  • Loading states

Recording and Replaying

Save Session

  1. File → Save Session
  2. Charles saves all traffic as .chls file
  3. Share with team for debugging

Export Requests

  1. Select requests
  2. File → Export Session
  3. Formats: HAR, JSON, Text, cURL

Export as cURL: Right-click → Copy cURL Request

curl -X POST 'https://api.example.com/login' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@test.com","password":"123"}'

Repeat Requests

  1. Select request
  2. Right-click → Repeat (single)
  3. Right-click → Repeat Advanced (multiple with delay)

Common Testing Scenarios

Testing Error Handling

Mock server errors:

// Create error-500.json
{
    "error": "Internal Server Error",
    "code": 500
}

Map Local with HTTP status:

  1. Tools → Rewrite
  2. Add rule for response status
  3. Match: any status, Replace: 500

Testing Timeout Behavior

  1. Enable Throttling
  2. Set very high latency (30000ms)
  3. Observe app timeout handling

Testing Empty States

Mock empty array response:

// empty-list.json
{
    "items": [],
    "total": 0
}

Authentication Testing

Test expired token handling:

  1. Breakpoint on request
  2. Modify Authorization header to invalid value
  3. Verify app handles 401 correctly

Charles Proxy with AI Assistance

AI tools can help with network debugging workflows.

What AI does well:

  • Explain HTTP status codes and headers
  • Generate mock JSON responses
  • Convert cURL to code snippets
  • Analyze traffic patterns

What still needs humans:

  • Identify which traffic matters
  • Understand business context of data
  • Security implications of findings
  • Real device testing decisions

FAQ

What is Charles Proxy?

Charles Proxy is an HTTP proxy and monitor application. It sits between your application and the internet, capturing all HTTP and HTTPS traffic for inspection and modification. Testers use it to debug API issues, mock server responses, simulate network conditions, and understand how applications communicate with backends.

Is Charles Proxy free?

Charles Proxy offers a 30-day free trial with 30-minute session limits. After trial, a license costs $50 per user (one-time purchase). Free alternatives include mitmproxy (command-line, open source), Proxyman (macOS native), and browser DevTools for basic inspection.

How do I use Charles with mobile apps?

Configure your mobile device’s WiFi proxy settings to point to your computer’s IP address and Charles port (default 8888). Both devices must be on the same network. For HTTPS traffic, install Charles SSL certificate on your device and trust it in security settings. Android 7+ apps may need additional configuration to trust user certificates.

Can Charles modify API responses?

Yes. Charles offers several modification options: Breakpoints for real-time editing, Map Local to return local files, Map Remote to redirect to different servers, and Rewrite rules for automatic header/body modifications. These features let you test edge cases, error handling, and UI states without backend changes.

Official Resources

See Also