Monitor Network Traffic with Charles Proxy

Charles Proxy helps debug network traffic in Vega apps and inspect HTTPS connections that handle sensitive information. It acts as a middleman between your app and server, intercepting network traffic and allowing you to:

• Monitor all network traffic
• Identify network issues
• Modify requests and responses
• Analyze performance

Prerequisites

Install the following requirements:

1. Charles Proxy (version 4.6 or higher)

   For transport layer security (TLS) version 1.3 compatibility, download Charles 5.

2. Vega SDK latest version.

3. A Vega app project.

Supported protocols

Configure your app to use one or more of these protocols for the Charles Proxy to capture its traffic:

• HTTP
• HTTPS
• XMLHttpRequest
• Media Player requests
• Websocket requests

Set up Charles Proxy

1. Open Charles Proxy and grant macOS proxy privileges when prompted.

2. Set HTTP Proxy Port to 8888.

   

   1. Go to Proxy > Proxy Settings.

   2. Enter 8888 in the HTTP Proxy Port field.

   3. Click OK.

3. Configure Secure Sockets Layer (SSL) Proxying.

   

   a. Go to Proxy > SSL Proxying Settings.

   b. Click the SSL Proxying tab.

   c. Click Add in the Include section.

   d. Leave the Host box empty in the Edit Location dialog.

   e. Enter 443 in the Port field.

   f. Click OK.

4. Generate a root certificate.

   a. Go to Help > SSL Proxying > Save Charles Root Certificate.

   b. Enter proxy-cert.pem in the Save As field.

   c. Save the certificate in your preferred location.

   d. Click Save.

Add Charles Proxy to your Vega apps

1. At the command prompt, navigate to your app:

   For example:

   Copy code Copied to clipboard.

   cd keplersampleapp
   

   Tip: Replace keplersampleapp with your app name.

2. Clean the project:

   Copy code Copied to clipboard.

   kepler clean
   

3. Create an assets/raw folder in your project directory.
4. Move the proxy-cert.pem file to the assets/raw folder.

5. Create a proxy-config.json file in the assets/raw folder.

   Example proxy-config file:

   Copy code Copied to clipboard.

    {
        "enableSSLProxying": true,
        "caBundleFile": "raw/proxy-cert.pem",
        "host": "localhost",
        "port": 8888
    }
   

The following table lists the required fields for the proxy-config.json file.

Field	Type	Description	Required
caBundleFile	String	The path to the root certificate file, relative to the assets directory.	Yes
enableSSLProxying	Boolean	Determines whether to trust the caBundleFile certificate. If set to false, caBundleFile has no effect. Due to security implications, WebView only trusts caBundleFile for a debug variant of an app. On React Native for Vega, this applies to apps that report development for the NODE_ENV process environment as mentioned in Develop Your App with WebView.	Yes
host	String	The system enables HTTP, HTTPS, and WebSocket (non-WebView) traffic proxying if you provide a valid host and port. For apps running on the Vega Virtual Device, use 10.0.2.2 as the host value.	Yes
port	Number	Specifies the port on the host for proxying.	Yes

Debug your app

1. Install dependencies:

   Copy code Copied to clipboard.

    npm install
   

2. Run and build your app:

   Copy code Copied to clipboard.

    npm run build:app
   

3. Install the app on your Vega Virtual Device or Fire TV Stick.

Monitor Traffic

1. Go to Proxy > Start Recording.

2. Launch your app on your Vega Virtual Device or Fire TV Stick.

   Charles Proxy displays the network requests made by your app. You can view the details in the Structure or Sequence tab.

   Note: Charles Proxy displays SSL traffic as decrypted.
   Important: Verify your proxy configuration if no traffic appears. Check your Charles root certificate installation if you see SSL errors.

3. Test Charles connection:

   Copy code Copied to clipboard.

    curl -x localhost:8888 www.amazon.com
   

Set up port forwarding

Port forwarding directs the device to send requests meant for a specific port to your computer instead.

Complete these steps only for Fire TV Stick (not needed for the Vega Virtual Device):

1. At the command prompt, run:

   Copy code Copied to clipboard.

   kepler exec vda reverse tcp:<remote-port> tcp:<local-port>
   

   Tip: Replace <remote-port> with the port you configured in the proxy-config.json file on your Fire TV Stick. Replace <local-port> with the port you configured for Charles Proxy on your development machine (port 8888).

   Example:

   Copy code Copied to clipboard.

   kepler exec vda reverse tcp:8888 tcp:8888
   

   Important: Stop port forwarding when you're done debugging to restore your device normal network configuration.

2. Delete the following files before submitting your app for production:

   • proxy-config.json
   • certificate files (for example, assets/raw/proxy-cert.pem)

3. Clean and rebuild your project:

   Copy code Copied to clipboard.

   kepler clean
   

   Copy code Copied to clipboard.

   npm install
   

   Copy code Copied to clipboard.

   npm run build:app
   

Add or modify proxy-config.json file

To update your configuration:

1. Complete the steps in Set up Charles Proxy.
2. Uninstall your existing app.
3. Install your new app.

Use Charles Proxy across multiple machines

Learn how to monitor Vega app network traffic across development and test machines. Use this approach to share a .vpkg configured with Charles proxy for team testing.

On the development machine

1. Complete the steps in Set up Charles Proxy.

2. Export the root certificate and private key:

   

   a. Go to Help > SSL Proxying > Export Charles Root Certificate and Private Key…

   b. In the Export Charles Root Certificate and Private Key dialog:

   - Set a strong password (securely share this information with your testers later)
   - Name the file (for example, `proxy-root-cert-private-key.p12`)
   - Choose a download location
   

3. Extract the root certificate using one of the following options:

   Option 1 (Preferred):

   • Go to Help > SSL Proxying > Save Charles Root Certificate
   • Name the file (for example, proxy-cert.pem)

   Option 2 (Using OpenSSL):

   Copy code Copied to clipboard.

   openssl pkcs12 -in proxy-root-cert-private-key.p12 -out proxy-cert.pem -clcerts -nokeys
   

4. Complete the steps in Add Charles Proxy to your Vega apps.

5. Securely share the following information with your testers:

   • proxy-root-cert-private-key.p12 file
   • password
   Important: Use secure methods to share the certificate file and password as they provide access to encrypted traffic.

On the test machine

Testers should complete this section.

1. Complete the steps in Set up Charles Proxy.

2. Import the shared certificate.

   

   a. Go to Proxy > SSL Proxying Settings > Root Certificate > Import P12.

   b. Select the shared proxy-root-cert-private-key.p12 file.

   c. Enter the password provided by your development team.

3. Complete the steps in Set up port forwarding.

4. Complete the steps in Monitor traffic.

   Important: Verify port forwarding configuration if no traffic appears. Check certificate import if SSL errors occur.

Best practices for SSL configuration

To ensure reliable operation with Charles Proxy:

• Verify your proxy-config.json file has correct formatting and certificate paths.
• Start Charles Proxy before launching your app.

Troubleshooting

If you encounter issues when using Charles Proxy with Vega development tools, see Charles Proxy Troubleshooting for common problems and solutions.

Related topics

• Charles Proxy documentation.

---

Last updated: Sep 30, 2025