# Proxyman Documentation (full text) > Every page of https://proxyman.com/docs/ in one file, in sidebar order. Page index: https://proxyman.com/docs/llms.txt --- Source: https://proxyman.com/docs/ # Overview > Proxyman is an HTTP debugging proxy for macOS, Windows, Linux, iOS and Android. Capture, inspect and change HTTP/HTTPS traffic from apps and devices. ## 1. Proxyman Proxyman is a fast HTTP debugging proxy for macOS, Windows, Linux, iOS and Android. Use it to view and change HTTP/HTTPS requests and responses from apps, browsers and devices, including iOS devices, iOS Simulators, Android devices and Android Emulators. ![Proxyman for macOS 26 main window with captured requests, request query and JSON response body](https://proxyman.com/docs/assets/new_dashboard_macOS_26.jpg) _Proxyman Dashboard for macOS 26_ ## Video [Video: Capture HTTP and HTTPS traffic with Proxyman](https://proxyman.com/videos/capture-http-https-traffic) (25 seconds) ## 2. Features * [x] ✅ Intercept HTTP/HTTPS (SSL) requests from your Mac, iOS Simulators, iOS devices, Android devices and Android Emulators 📱. * [x] Built for Apple Silicon and macOS 26 Tahoe * [x] ✅ Built on Apple SwiftNIO for high performance * [x] 🦋 Modern and intuitive UI. * [x] 🍸 Liquid Glass UI for macOS 26 * [x] ⭐️ Native app on macOS. ElectronJS-based app for Windows and Linux * [x] 📱 Apps for iOS and Android to capture traffic directly on your phone * [x] 👑 Debugging tools: Compose, Repeat, ... * [x] 🛠 Advanced Tools: Map Local, Map Remote, Breakpoint, Allow List, Block List, External Proxying, No Caching, Clear Cache, Protobuf, Scripting (Rewrite), and Diff. * [x] 👨‍💻 Customizable workspace. * [x] 🖥 Supports macOS 14 Sonoma or later ## 3. Download * Download the latest [macOS app](https://proxyman.com/release/osx/Proxyman_latest.dmg) * Download the latest [Windows app](https://proxyman.com/release/windows/Proxyman_latest.dmg) * Download the latest [Linux app](https://proxyman.com/release/linux/proxyman_latest) * Download the latest [iOS app](https://apps.apple.com/us/app/proxyman/id1551292695) * Download the latest [Android app](https://play.google.com/store/apps/details?id=com.proxyman.proxymanandroid) * See all platforms on the [Proxyman download page](https://proxyman.com/download) * Download the macOS app with Homebrew Cask: ```bash $ brew install --cask proxyman ``` ## 4. GitHub The [Proxyman GitHub repo](https://github.com/ProxymanApp/Proxyman) is where you can create tickets for feature requests, start discussions, report bugs and talk to the Proxyman team. > **Tip:** We welcome all bug reports and feature requests 😍 To get notified about every Proxyman release, watch the repo. ## 5. Milestone You can check the current [Milestone](https://github.com/ProxymanApp/Proxyman/milestones) in the GitHub repo. ## Learn more * [Getting Started with Proxyman: Capture HTTP and HTTPS](https://proxyman.com/posts/2019-06-14-getting-started-with-proxyman) * [Getting Started with Proxyman for iPhone and iPad](https://proxyman.com/posts/2021-10-17-Getting-Started-With-Proxyman-For-iOS) * [Proxyman is now available on Android](https://proxyman.com/posts/2026-05-25-Proxyman-is-now-available-on-Android) --- Source: https://proxyman.com/docs/changelog # Changelog > Read the Proxyman changelog and release notes for macOS, Windows and Linux, and download an older version of the Proxyman app when you need one. You can see the changelog and download an old version at: * Proxyman for macOS Changelog: [https://proxyman.com/changelog](https://proxyman.com/changelog) * Proxyman for macOS Changelog before 2024: [https://proxyman.com/changelog-archive](https://proxyman.com/changelog-archive) * Proxyman for Windows and Linux Changelog: [https://proxyman.com/changelog-windows](https://proxyman.com/changelog-windows) * GitHub Release Page: [https://github.com/ProxymanApp/Proxyman/releases](https://github.com/ProxymanApp/Proxyman/releases) > **Tip:** We recommend using the latest Proxyman version since it includes more features, bug fixes, and better performance. --- Source: https://proxyman.com/docs/license # License > Learn what Proxyman Pro includes, how the trial works, and how to buy, activate, move or remove a Proxyman license key on Mac, Windows, Linux and iOS. ## Proxyman Pro You can try all debugging tools with the Trial version, which is limited to 2 pinned domains, 2 rules for each debugging tool, and no new tabs. The **Pro version** comes with: * A year’s worth of macOS, Windows, and Linux updates * 1 Mac device per seat * Premium [Proxyman for iOS](https://proxyman.com/ios) (2 devices per seat) * [Tab View](https://proxyman.com/docs/basic-features/multiple-tabs) * [Split View](https://proxyman.com/docs/basic-features/split-view) for macOS * Unlimited Pinned Domains / Apps * Unlimited rules for all Advanced Debugging Tools (e.g., [SSL Proxying List](https://proxyman.com/docs/basic-features/ssl-proxying), [Map Local](https://proxyman.com/docs/advanced-features/map-local), [Map Remote](https://proxyman.com/docs/advanced-features/map-remote), [Breakpoint](https://proxyman.com/docs/advanced-features/breakpoint), [Allow/Block List](https://proxyman.com/docs/advanced-features/blacklist), [Protobuf](https://proxyman.com/docs/advanced-features/protobuf), [Scripting](https://proxyman.com/docs/scripting/script), [Network Conditions](https://proxyman.com/docs/advanced-features/network-throttling), [Multiple Filters](https://proxyman.com/docs/advanced-features/multiple-filters), [Reverse Proxy](https://proxyman.com/docs/advanced-features/reverse-proxy), [Request/Response Diff](https://proxyman.com/docs/advanced-features/diff), etc). ## Trial Evaluation Duration * Personal Purpose: No time limit. * Business Purpose: 2 weeks. After that, please consider buying a license. ## Demo Key If you're a team or a company, you can request a 2-week demo key. Please contact support@proxyman.com. ## Buy Proxyman License Go to the [Proxyman Pricing page](https://proxyman.com/pricing) to buy Proxyman licenses. ## Manage Proxyman License If you're the owner of the Proxyman license key, you can manage your devices by using the [License Manager](https://proxyman.com/docs/license-manager). ## Activate License ### macOS/Windows/Linux app 1. After you buy a Proxyman license, you will receive a license key by email. 2. To activate it, open the Proxyman app (macOS/Windows/Linux) -> Proxyman Menu -> Buy Proxyman Pro. 3. Click the "Activate License" button and enter your license key. ![Proxyman Pro window with the Activate License button and the Free and Pro feature list](https://proxyman.com/docs/assets/Screenshot%202024-02-18%20at%2009.20.49.png) _Activate License Key on macOS/Windows/Linux app_ ### Activate the License key with your Corporate proxy * Available from Proxyman macOS 5.5.0 or later * Some companies use a Corporate Proxy, so Proxyman can't reach the license server to activate the key. To fix it, follow these steps: 1. Open Tools -> Proxy Settings -> External Proxy Settings… 2. Check "Enable External Proxy Tool" 3. Check the HTTP and HTTPS checkboxes 4. For each of HTTP and HTTPS: Enter your Proxy Host and Port. 5. If your corporate proxy needs authentication, enter the username and password. 6. Done ✅ 7. Try to activate the License Key again. ![Proxyman External Proxy settings with Web Proxy (HTTP) and Secure Web Proxy (HTTPS) set to proxy.example.com:8080](https://proxyman.com/docs/assets/proxyman-external-proxy-settings.jpg) _Use External Proxy to activate your license key_ ### iOS app Your Proxyman license key also works with the Proxyman iOS app. 1 seat can be activated on 2 iOS devices. 1. Download the iOS app from the App Store: [https://apps.apple.com/us/app/proxyman-network-debug-tool/id1551292695](https://apps.apple.com/us/app/proxyman-network-debug-tool/id1551292695) 2. Open the More Tab (on the Right-Bottom TabBar) -> Face ID & Passcode -> Unlock -> Enter your license key. 3. Done ## Activate License by CLI (macOS Only) If you have many licenses, you can activate them automatically from the command line. 1. Download the Proxyman app and copy it to the `/Applications` folder 2. **Open and close the app at least once.** This sets up some required configuration. 3. Open Terminal and run the following command: To **Activate**: ```bash $ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli activate ``` To **Unlink** device: ```bash $ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli unlink ``` ![Terminal showing proxyman-cli help with the activate and unlink subcommands](https://proxyman.com/docs/assets/128307433-8887f444-5c94-42bb-8ec6-f30bce271f50.png) See the [Proxyman command-line tool](https://proxyman.com/docs/command-line) page for all `proxyman-cli` commands. ### Activate by URL You can also activate a Proxyman license with a URL: 1. Download and open Proxyman at least once. 2. Open the URL in Safari or Google Chrome. `proxyman://activate?key=` ### Remove License You can remove your license from your devices and then activate it on your new devices as long as you have enough available seats. #### From your current devices On macOS, open Proxyman -> Proxyman Menu -> Proxyman Pro… -> click the "More" button -> "Revoke this Device…". #### With License Manager 1. Open the [License Manager](https://proxyman.com/license-manager/access-link) 2. Enter the email address that you used to buy the license 3. Open the access link from your email. 4. Click on the device to remove it. ### Activate License with Corporate Proxy Server From Proxyman 4.12.0 or later, you can make Proxyman use your Corporate Proxy in Tools Menu -> Proxy Settings -> External Proxy Settings… -> Set the HTTP / HTTPS Proxy. See [Activate the License key with your Corporate proxy](#activate-the-license-key-with-your-corporate-proxy) for the steps. --- Source: https://proxyman.com/docs/license-manager # License Manager > Use the Proxyman License Manager to check your license status, renew or extend your key, and remove old Mac or iOS devices from your seats. License Manager is an easier way to manage your license. It allows you to: * See your License status (Purchase date, Expiry date, Number of Mac / iOS Seats) * See a list of devices that are activated with your license key * Renew / Extend your license key * Remove Mac or iOS devices ![Proxyman License Manager page with license status, Mac and iOS seat counts, and active devices](https://proxyman.com/docs/assets/Proxyman_License_Manager.png) ## How to use it? 1. Open the [Proxyman License Manager](https://proxyman.com/license-manager/access-link) 2. Enter the email that you used to buy the license key. 3. You will receive an `Access Link` by email. 4. Open it to access the License Manager. > **Note:** If you don't remember which email you used to buy your Proxyman License, please contact us at support@proxyman.com --- Source: https://proxyman.com/docs/raycast # Raycast > Control Proxyman from Raycast. Install the Proxyman Raycast extension to toggle the system proxy, debugging tools and recording with a few keystrokes. ## Raycast Store Proxyman macOS 5.10.0 or later supports Raycast commands, so you can control Proxyman quickly from Raycast: * Toggle System Proxy * Toggle Map Local Tool * Toggle Breakpoint * Toggle Blocklist * Toggle Allowlist * Toggle Map Remote * Toggle Scripting * Toggle External Proxy * Toggle SOCKS Proxy * Toggle Network Condition * Toggle SSL Proxying List * Toggle Record Traffic * Clear Session ![Raycast search for proxyman listing commands such as Toggle System Proxy, Toggle Breakpoint and Clear Session](https://proxyman.com/docs/assets/raycast_and_proxyman.jpeg) _Proxyman and Raycast_ You can also control Proxyman from Terminal or your own scripts with the [Proxyman command-line tool](https://proxyman.com/docs/command-line). ## Download * Store: [https://www.raycast.com/noah\_tran/proxyman](https://www.raycast.com/noah\_tran/proxyman) * Click the button below 👇 [![Install the Proxyman extension from the Raycast Store](https://www.raycast.com/noah\_tran/proxyman/install\_button@2x.png?v=1.1)](https://www.raycast.com/noah\_tran/proxyman) --- Source: https://proxyman.com/docs/command-line # Command-line > Use proxyman-cli to control Proxyman for macOS from Terminal: export and import rules, toggle tools and the system proxy, export logs and manage certs. Proxyman for macOS comes with `proxyman-cli`, a command-line tool to control Proxyman from Terminal and your own scripts ✅. You can access the tool at `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli` To see all commands for your installed version, run: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli --help ``` ## 1. Export Proxyman config Export all debugging tools rules, such as SSL Proxying List, Breakpoint, Map Local, Scripting, Block List, Allow List, Reverse Proxy, and Network Conditions. ```bash $ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -h OVERVIEW: Export all debugging tools rules (Breakpoint, SSL Pinning, Map Local, Map Remote, Scripting, etc). USAGE: proxyman-cli export [--mode ] --output OPTIONS: -m, --mode Export Mode (all = "All debugging tools's rules", enabledRules = "Only enabled rules"). (default: all) -o, --output A Output file to save the config to. --version Show the version. -h, --help Show help information. ``` > **Note:** By default, the `export` command will export all rules. To exclude particular rules, please uncheck the "Enabled" column in each debugging tool and use the `-m enabledRules` ### For example: * Export all debugging tool rules: `$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -o ~/Desktop/data.json` * Only export enabled rules: `$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -m enabledRules -o ~/Desktop/data.json` ## 2. Import Proxyman config Import Proxyman debugging tools rules that you have exported by the export command. ```bash $ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -h OVERVIEW: Import config to Proxyman. USAGE: proxyman-cli import [--mode ] --input OPTIONS: -m, --mode Import Mode (append = "Append to the existing rules"), override = "Import and Replace all existing rules". (default: append) -i, --input A input file to import. --version Show the version. -h, --help Show help information. ``` > **Note:** By default, new imported rules will be appended to the existing debugging rules. To override all rules, use `-m override` ### For example: * Import all debugging rules by appending them: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -i ~/Desktop/data.json ``` * Import, but override all my existing rules: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -m override -i ~/Desktop/data.json ``` ## 3. Activate/Unlink License See the License page for the commands to activate and unlink a license. - [License](https://proxyman.com/docs/license) ## 4. Toggle HTTP System Proxy From Proxyman 4.8.0 and later, you can turn the macOS System Proxy on or off from the command line. The [Raycast extension](https://proxyman.com/docs/raycast) uses it. ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy on /Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy off ``` Reference: [https://github.com/ProxymanApp/Proxyman/issues/1626#issuecomment-1545862020](https://github.com/ProxymanApp/Proxyman/issues/1626#issuecomment-1545862020) ## 5. Clear Session * You can clear the current Session from the command line. Available for Proxyman 4.12.0 and later. ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli clear-session ``` ## 6. Toggle Debugging Tools * Toggle Breakpoint, Map Local, and Scripting Tool by command line. Available for Proxyman 4.12.0 and later. ```bash # Scripting /Applications/Proxyman.app/Contents/MacOS/proxyman-cli scripting on /Applications/Proxyman.app/Contents/MacOS/proxyman-cli scripting off # Map Local /Applications/Proxyman.app/Contents/MacOS/proxyman-cli maplocal on /Applications/Proxyman.app/Contents/MacOS/proxyman-cli maplocal off # Breakpoint /Applications/Proxyman.app/Contents/MacOS/proxyman-cli breakpoint on /Applications/Proxyman.app/Contents/MacOS/proxyman-cli breakpoint off ``` * From Proxyman macOS 6.3.0 or later, you can also toggle these tools the same way: `map-remote`, `block-list`, `allow-list`, `reverse-proxy`, `network-condition`, `no-caching`, and `dns-spoofing`. * Use `open` instead of `on` or `off` to open the tool window, for example `proxyman-cli map-remote open`. `no-caching` only supports `on` and `off`. * Proxyman must be running for these commands to work. ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli map-remote on /Applications/Proxyman.app/Contents/MacOS/proxyman-cli block-list off /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-condition open ``` ## 7. Install the Proxy Helper Tool by command line From Proxyman macOS 4.12.0 or later, you can install the Helper Tool without the GUI. ```bash sudo /Applications/Proxyman.app/Contents/MacOS/proxyman --install-privileged-components ``` ## 8. Export Proxyman Log **Proxyman macOS v5.11.0+ now supports:** * Export all (ProxymanSession Format) ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output" ``` * Export certain domains (Only Host, no scheme, no port, no paths, and no Query) ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com' ``` **From Proxyman macOS 5.20.0+, you can export with Raw or HAR format.** * Export All - RAW Request/Response Format ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output" --format raw ``` * Export All - HAR Format ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output" --format har ``` * Export certain domains - RAW Request/Response Format ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com' --format raw ``` * Export certain domains - HAR Format ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com' --format har ``` **From Proxyman macOS 6.2.0+, you can add `--since ` to export only the flows from this flow ID onward (the flow with this ID is included). It works with all export formats.** Supported formats for `--format` are `proxymansession` (default), `har`, and `raw`. ## 9. Import Custom Root Certificate * ✅ Import Custom p12 Root Certificate to Proxyman * Automatically Trust the certificate in System Keychain (sudo required) * Available from Proxyman macOS 5.15.0 or later ### Install and trust ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli install-root-cert --password --trust ``` ### Install but not trust (you might need to trust it manually in the Keychain) ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli install-root-cert --password ``` ## 10. Export Current IP and Port * Available from Proxyman macOS 6.7.0 or later * Get the current Listening IP & Port in JSON format 
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy-host
The output has an `ip` and a `port` field, for example `{"ip":"192.168.1.10","port":9090}`. If Proxyman only listens on localhost, the IP is `127.0.0.1`. ## 11. Add, Remove, Replace the Custom certificates (Client and Server) * Available on Proxyman macOS 6.10.0 or later ✅ * Supports P12 certificates with a password * For client certificates, `--port` defaults to `443` ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert add server ~/Desktop/mycert.p12 --password 123 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert add client ~/Desktop/mycert.p12 --password 123 --host myserver.com --port 443 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert replace server ~/Desktop/mycert.p12 --password 123 --name mycert.p12 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert replace client ~/Desktop/mycert.p12 --password 123 --host myserver.com --port 443 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert remove server --name mycert.p12 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert remove client --host myserver.com --port 443 ``` ## 12. External Proxy CLI * Proxyman macOS 6.12.0 or later ✅ ### Enable Enable External Proxy without changing the saved configuration: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable ``` * Enable and configure a proxy mode: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable http --host proxy.example.com --port 8080 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable https --host proxy.example.com --port 8443 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable socks --host proxy.example.com --port 1080 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable pac --url https://example.com/proxy.pac ``` ### Disable Disable the entire External Proxy feature: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable ``` * Disable only one proxy mode: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable http /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable https /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable socks /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable pac ``` ### Open the settings Open the External Proxy settings window in Proxyman: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy open ``` ## 13. CRUD for all debugging tools > **Tip:** Only available on Proxyman macOS 6.14.0 or later ### Supported tools `block-list`, `allow-list`, `ssl-proxying`, `map-local`, `map-remote`, `breakpoint`, `scripting`, `network-condition`, `reverse-proxy`, `protobuf`, and `dns-spoofing`. ### Common commands Replace `` with one of the supported tools and `` with a rule ID from `list` or `get`. ```bash # Read rules /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules list /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules list --enabled true /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules get # Change one rule /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules update --name "New name" /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules delete # Turn a whole tool on or off /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules enable /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules disable # Turn one rule on or off /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules enable /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules disable ``` `enable ` also turns on its tool when needed. Turning off a tool keeps each rule's own enabled setting. Updates change only the fields you send; delete removes the rule right away. `map-local`, `map-remote`, `breakpoint`, and `scripting` also have a `folders` command to manage rule folders, and their `list` and `create` commands accept `--folder `. Run `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local folders --help` to see the options. ### Create a rule These are the smallest create commands. Optional flags let you set more fields. Run `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules create --help` to see them. ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules block-list create https://ads.example.com/* /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules allow-list create https://api.example.com/* /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules ssl-proxying create '*.example.com' --list include /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local create https://api.example.com/* --path ./response.json /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-remote create https://old.example.com/* https://new.example.com/ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules breakpoint create https://api.example.com/* --phase both /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules scripting create https://api.example.com/* --script-file ./rule.js /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules network-condition create --profile 3g /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules reverse-proxy create https://upstream.example.com --local-port 8080 /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules protobuf create https://api.example.com/* --request-type package.Request /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules dns-spoofing create example.com 127.0.0.1 ``` Common rule flags include `--name`, `--enabled true|false`, `--method`, `--match wildcard|regex`, and `--include-subpaths true|false` when the tool supports them. Names are optional. If you omit an optional value, Proxyman uses that tool's normal default. ### JSON input For create and update, use `--input ` to send a JSON object. Use `--input -` to read JSON from standard input. Do not mix `--input` with field flags. ```bash printf '%s' '{"url":"https://api.example.com/*","name":"Local API","enabled":true}' \ | /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local create --input - /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local update --input ./map-local-change.json ``` When Proxyman is closed, the command returns JSON with `ok: false` and the `app_not_running` error code. Input errors use exit code `2`; other errors use exit code `1`. ## 14. Company Policy ### MCP (Proxyman macOS 6.15.0+) * Enable or disable the [MCP](https://proxyman.com/docs/mcp) feature, even when Proxyman is closed * If MCP is disabled from the command line, users can't enable it again in the Settings Disable MCP and lock the Settings toggle: ``` /Applications/Proxyman.app/Contents/MacOS/proxyman-cli mcp off ``` Enable MCP and unlock the toggle: ``` /Applications/Proxyman.app/Contents/MacOS/proxyman-cli mcp on ``` ## 15. HTTP version Read or change the global [HTTP/2](https://proxyman.com/docs/basic-features/http2) policy. Keep Proxyman open; these commands work even when MCP is disabled. ```bash # Read the current policy /Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version status # Prefer HTTP/2, with HTTP/1.1 fallback /Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version set prefer_http2 # Turn the HTTP/2 preference off /Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version set http1_only ``` HTTP/2 is off by default. Changing the policy closes active HTTP, WebSocket, and Server-Sent Events connections and refreshes the Compose client. Setting the current policy again leaves connections open. The policy does not prove which protocol a request used. Check the captured request and upstream connection. With Network Extension capture, a client offering only `h2` keeps HTTP/2 even under `http1_only`. Both commands return JSON. Status includes `httpVersionMode` and `http2Enabled`; `set` also includes `previousMode` and `changed`. For example, changing from HTTP/1 to the HTTP/2 preference returns: ```json { "success": true, "data": { "httpVersionMode": "prefer_http2", "http2Enabled": true, "previousMode": "http1_only", "changed": true } } ``` ## 16. Network Extension Manage [Network Extension](https://proxyman.com/docs/advanced-features/network-extension) installation and capture from the command line. Keep Proxyman open; MCP does not need to be enabled. > **Note:** Network Extension requires the direct Proxyman edition and macOS 26 or later. Installation and capture require Proxyman PRO. Status and uninstall remain available without PRO. Setapp does not support Network Extension. ```bash # Read installation and capture status without changing either /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension status # Install or update the bundled extension without enabling capture /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension install # Enable capture, installing the extension if necessary /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension enable # Stop capture and keep the extension installed /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension disable # Retry requested installation or capture after resolving an error /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension retry # Stop capture and remove the extension and its saved network configurations /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension uninstall ``` `install` leaves capture off if it is already off. `enable` starts capture and turns the helper-based system proxy off. The system proxy cannot be enabled while Network Extension capture is on. `disable` and `uninstall` close existing connections through the provider, including direct TCP connections. Afterwards, the system proxy follows **Auto Override System Proxy Settings at Launch**. macOS may ask for approval or a restart. Complete those steps, then run `network-extension status` again. A successful command means the request was accepted; it does not mean installation or capture has finished. If an operation is busy or times out, read status before repeating it. HTTPS decryption still requires a trusted Proxyman certificate and matching SSL Proxying rules. Reconnect clients to capture newly opened connections. ### Read the JSON status | Field | Meaning | | --- | --- | | `supported` | Whether this app and macOS version support Network Extension. Unsupported hosts return `false` and reject changes. | | `installed`, `installedBuild`, `bundledBuild` | Installation reported by macOS and the build bundled with the running app. | | `systemExtensionEnabled` | Whether macOS reports the installed extension as enabled. | | `proAvailable` | Whether Proxyman PRO is available for installation and capture. | | `captureEnabled` | Whether capture has been requested. | | `captureActive` | Whether the provider has acknowledged the capture session. | | `state`, `message` | Current app state and a readable explanation. | | `operationPending` | Whether an installation, removal, or capture startup is in progress. | | `approvalRequired`, `restartRequired` | Whether approval or a restart is needed. | | `removalPending` | Whether macOS still has extension records awaiting removal, including after an app relaunch. | | `systemProxyEnabled` | Whether Proxyman currently reports the macOS system proxy as enabled. | Supported hosts return these fields under `data`. `disable` does not wait for an installation query, so `installed` is `null` in its response. Use `status` for a fresh installation check. ### JSON output and exit codes The `http-version` and `network-extension` command groups return a JSON response with `success`, `data` when available, and `error` on failure. * `0`: The read succeeded or the change was accepted. Check Network Extension status for completion. * `1`: The command failed, Proxyman is closed, or the command timed out. * `64`: Invalid command-line arguments. Parser errors and help use plain text. Check the syntax supported by your installed app with: ```bash /Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version --help /Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension --help ``` --- Source: https://proxyman.com/docs/mcp # MCP > Connect Codex, Claude Code, or Cursor to Proxyman MCP to inspect captured HTTP/HTTPS traffic and create debugging rules from your AI assistant. Proxyman MCP connects your AI assistant to the Proxyman macOS app running on your computer. Use it to inspect captured requests and responses, investigate failures, and create debugging rules. Keep Proxyman open and capture the traffic you want to investigate before asking your assistant to analyze it. ## 1. What is Proxyman MCP? **Proxyman MCP** (Model Context Protocol) is a feature that enables AI assistants (Codex, Claude Code, Cursor, and other MCP-compatible tools) to directly interact with the Proxyman macOS app. It allows AI to inspect HTTP traffic, create debugging rules, and control Proxyman - all through natural language conversations. The architecture consists of two components: * **MCP HTTP Server** - Runs inside Proxyman app on localhost with token-based authentication * **MCP CLI Server** - A stdio-based MCP server that AI tools connect to, which forwards commands to Proxyman > **Note:** Check out the [Proxyman SKILL.md](https://proxyman.com/docs/skill-md) for your AI Agents ### ✅ Example Prompts * Show me the last 10 API requests to api.example.com * Create a breakpoint for all POST requests to /api/users * Export the failed request as a cURL command * Enable SSL proxying for \*.stripe.com * Create a new Script to change the status code, headers, body. * Create Map Local, Breakpoint Tools with given URL ![Claude using Proxyman MCP to create a Scripting rule that changes a query, adds a header and sets status 301](https://proxyman.com/docs/assets/Screenshot%202026-03-16%20at%2011.20.29.jpg) _Create a Scripting rule with Proxyman MCP_ ## 2. Benefits
BenefitDescription
AI-Powered DebuggingAsk AI to analyze captured traffic, find specific requests, or explain API responses
Hands-Free Rule CreationCreate breakpoints, map local/remote rules through conversation
Faster WorkflowExport cURL commands, filter flows, and manage sessions without switching context
Secure by DesignLocalhost-only server with per-session token authentication
IDE IntegrationWorks with Codex, Claude Code, Cursor and other MCP-compatible tools
## 3. How to add Proxyman MCP 1. **Enable MCP in Proxyman** * Open Proxyman → Settings → MCP Tab * Turn on **Enable MCP Server** to start the MCP Server 2. **Choose your MCP client:** In Proxyman Settings → MCP, select **Codex** or **Claude Code**, then use **Copy Command**. For **Cursor**, choose **Manual** and add the displayed configuration to Cursor's MCP settings. 3. Use the setup below for your client and installation. The command generated by Proxyman uses the path of your installed app, which may differ from these examples. Keep **Redact Sensitive Data Before Sending to AI** turned on for normal debugging. ![Proxyman MCP settings with Enable MCP Server on, Claude Code, Codex and Manual tabs, Copy, and Redact Sensitive Data](https://proxyman.com/docs/assets/proxyman-settings-mcp-tab.jpg) _MCP tab in Settings_ ### Codex * Production Version: ```bash codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" ``` * Setapp Version: ```bash codex mcp add proxyman -- "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server" ``` ### Claude Code * Production Version: ```bash claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" ``` * Setapp Version: ```bash claude mcp add proxyman --transport stdio -- "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server" ``` ### Manual For Cursor and other MCP clients, add the configuration from Proxyman's **Manual** tab to the client's MCP settings. Select the configuration for your installed Proxyman app. These examples show the `mcpServers` entry: * Production Version: ```json { "mcpServers": { "proxyman": { "command": "/Applications/Proxyman.app/Contents/MacOS/mcp-server" } } } ``` * Setapp Version ```json { "mcpServers": { "proxyman": { "command": "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server" } } } ``` 4. **Start using Proxyman MCP** * Ensure Proxyman is running * Ask your AI assistant to interact with Proxyman, for example: "Show the latest requests to api.example.com." * If the client cannot find Proxyman, check that MCP is enabled and the configured app path is correct, then reconnect the client. If it connects but finds no flows, make a new request and use the [missing-traffic checklist](https://proxyman.com/docs/troubleshooting/i-couldnt-see-any-traffics-on-proxyman). ## 4. Available Tools The tables below list common tools. Your MCP client shows the full list of tools for your installed Proxyman version. See the [Changelogs](#changelogs) for more tools. ### Read-Only Tools | Tool | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `get_version` | Returns Proxyman version and build number | | `get_proxy_status` | Returns recording state, proxy port, and SSL proxying status | | `get_flows` | Lists captured HTTP/HTTPS flows with optional filters (`limit`, `host_filter`, `method_filter`, `status_filter`) | | `get_flow_detail` | Returns full details of a specific flow including headers, body preview, query params, and cookies | | `list_rules` | Lists all debugging rules (breakpoints, map local, map remote, blacklist) | | `get_ssl_proxying_list` | Returns SSL proxying include/exclude domain lists | | `get_certificate_status` | Returns root certificate installation status | ### Write Tools | Tool | Description | Required Params | | ----------------------- | ------------------------------------------------------- | -------------------- | | `create_breakpoint` | Creates a breakpoint to pause/inspect matching requests | `url` (pattern) | | `create_map_local` | Returns custom responses for matching URLs | `url` (pattern) | | `create_map_remote` | Redirects requests from one URL to another | `from_url`, `to_url` | | `create_blacklist` | Blocks requests matching a URL pattern | `url` (pattern) | | `create_scripting_rule` | Creates a Scripting rule with custom JavaScript | `url`, `script_content` | | `enable_ssl_proxying` | Enables HTTPS decryption for a domain | `domain` | ### Session Control | Tool | Description | | ------------------ | ---------------------------------------------- | | `clear_session` | Clears all captured flows from current session | | `toggle_recording` | Starts or stops traffic recording | ### Flow Operations | Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | | `export_flow_curl` | Exports a captured request as a runnable cURL command | | `filter_flows` | Advanced filtering with multiple criteria (url, host, method, status, headers, body) supporting AND/OR combinations | ### App Control | Tool | Description | | --------------- | -------------------------------- | | `open_proxyman` | Launches Proxyman if not running | | `quit_proxyman` | Quits the Proxyman app | *** ## Changelogs ### MCP v3 (Proxyman macOS ≥ 6.8.0) | Name | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | get\_version | Get the current Proxyman macOS app version and build number | | get\_proxy\_status | Get current proxy status including recording state, port number, and SSL proxying status | | get\_flows | Get recent HTTP/HTTPS flows from Proxyman's active session data source | | get\_flow\_detail | Get detailed information about a specific flow including headers, body, query params, and cookies | | list\_rules | List all active debugging rules (breakpoints, map local, map remote, blacklist, scripting, dns spoofing, network condition, whitelist) | | get\_ssl\_proxying\_list | Get the current SSL Proxying configuration including enabled status and domain lists | | create\_breakpoint | Create a new breakpoint rule to pause and inspect/modify requests or responses matching a URL pattern | | create\_map\_local | Create a Map Local rule to return a custom response for matching requests | | create\_map\_remote | Create a Map Remote rule to redirect requests from one URL to another | | create\_blacklist | Create a Blacklist rule to block requests matching a URL pattern | | create\_scripting\_rule | Create a Scripting rule with custom JavaScript to modify requests/responses | | enable\_ssl\_proxying | Enable SSL Proxying for a specific domain to decrypt HTTPS traffic | | clear\_session | Clear all captured flows from the current session | | toggle\_recording | Start or stop recording HTTP traffic | | export\_flow\_curl | Export a captured HTTP request as a cURL command | | filter\_flows | Filter captured HTTP/HTTPS flows using advanced filter criteria | | get\_certificate\_status | Get the current status of Proxyman's root certificate | | install\_certificate | Install and trust the Proxyman root CA certificate | | uninstall\_certificate | Remove the Proxyman root CA certificate from the Keychain | | inject\_terminal | Launch a terminal app with Proxyman proxy environment variables injected | | get\_terminal\_manual\_command | Get a bash source command for manually setting proxy environment variables | | answer\_setup\_question | Answer setup questions about capturing HTTPS from iOS, Android, browsers, etc. | | search\_docs | Search the built-in Proxyman setup and troubleshooting doc index | | list\_setup\_workflows | List the supported setup workflows Proxyman MCP can guide users through | | list\_popular\_workflows | List popular setup workflows using Proxyman's curated fallback ranking | | open\_proxyman\_screen | Open a specific Proxyman guide or setup screen in the macOS app | | run\_guided\_setup | Run a one-click automation in Proxyman for browsers or Android emulators | | list\_reverse\_proxies | List configured Reverse Proxy entries | | create\_reverse\_proxy | Create a Reverse Proxy entry for localhost or custom local port routing | | generate\_code | Generate code from a captured HTTP flow in 18+ languages/frameworks | | create\_dns\_spoofing | Create a DNS Spoofing rule to redirect a hostname to a different IP address | | list\_dns\_spoofing | List all DNS Spoofing rules and their enabled status | | update\_dns\_spoofing | Update an existing DNS Spoofing rule | | get\_external\_proxy | Get the current External Proxy (upstream proxy) configuration | | set\_external\_proxy | Configure an External Proxy setting for a specific protocol kind | | toggle\_no\_caching | Toggle the No Caching feature (strips cache-related headers) | | inject\_electron | Launch an Electron app with Proxyman proxy configuration injected | | open\_proxyman | Launch the Proxyman macOS application | | quit\_proxyman | Quit the Proxyman macOS application | ### MCP v2 (Proxyman ≥ v6.7.0) * Built-in knowledge base covering iOS, Android, browsers, terminal, VPN, localhost, and third-party libraries * New commands: answer\_setup\_question, search\_docs, list\_setup\_workflows, open\_proxyman\_screen, run\_guided\_setup, create\_reverse\_proxy * MCP resources and prompt templates for chat clients * Reverse proxy create/list support ## Security * The server binds to `127.0.0.1` only (no network exposure) * Per-session cryptographic token stored in `~/Library/Application Support/com.proxyman.NSProxy/mcp-handshake.json` * The handshake file has `0600` permissions (owner-only access) * Sensitive data (auth tokens, passwords, API keys) is automatically redacted in responses ## Learn more * [How to use Proxyman MCP with Codex and Claude Code](https://proxyman.com/posts/how-to-use-proxyman-mcp-with-codex-and-claude-code) --- Source: https://proxyman.com/docs/skill-md # SKILL.md > Install the official Proxyman agent skills (SKILL.md) for Codex, Claude Code, Cursor and Copilot to inspect, replay and debug HTTP/HTTPS traffic. ## Proxyman Agent Skills Official agent skills for [Proxyman](https://proxyman.com), a web debugging proxy for inspecting, replaying, and debugging HTTP, HTTPS, WebSocket, device, and application traffic. The bundle covers installation, every macOS App Settings tab, certificate lifecycle and recovery, MCP connection and all current MCP operations, live documentation lookup, debugging-tool workflows, licensing, `proxyman-cli`, and HTTPS capture across devices and runtimes. Proxyman MCP controls a running local app through its bundled stdio bridge; it is not a cloud API. See the GitHub repo for the coverage and maintenance notes of each skill. * GitHub Repo: [https://github.com/ProxymanApp/proxyman-SKILL.md](https://github.com/ProxymanApp/proxyman-SKILL.md) ### Plugin * ✅ Install Proxyman Plugin at [OpenAI Marketplace](https://chatgpt.com/plugins/plugins_6a88afab118c8191970bbc714223ff14). ### Installation Install all skills: ```bash npx skills add ProxymanApp/proxyman-SKILL.md/skills ``` Install one skill: ```bash npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-download-setup npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-app-settings npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-certificates-recovery npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-mcp-setup npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-traffic-debugging npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-debugging-tools npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-license-management npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-cli npx skills add ProxymanApp/proxyman-SKILL.md --skill proxyman-https-capture ``` For manual installation, clone the repository and copy the desired folders under `skills/` into the agent's skills directory: ```bash git clone https://github.com/ProxymanApp/proxyman-SKILL.md.git ``` Restart or reload the agent afterward. | Agent | Skills directory | | -------------------------- | -------------------- | | OpenAI Codex CLI | `~/.codex/skills/` | | Claude Code/Desktop | `~/.claude/skills/` | | Cursor | `~/.cursor/skills/` | | GitHub Copilot CLI/VS Code | `~/.copilot/skills/` | ### Skills | Skill | Use it for | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxyman-download-setup` | Download, install, launch, and prepare Proxyman on macOS, Windows, or Linux. | | `proxyman-app-settings` | Audit, explain, and safely change every current macOS Settings tab, including build/license limitations and GUI-only boundaries. | | `proxyman-certificates-recovery` | Install/trust generated or custom roots, manage custom server/client identities, capture diagnostics, and safely use Help-menu recovery actions including Factory Reset. | | `proxyman-mcp-setup` | Connect an agent to the bundled stdio MCP bridge and troubleshoot handshake/tool discovery. | | `proxyman-traffic-debugging` | Inspect traffic and operate the complete current MCP surface: all 70 reviewed actions, resources, and prompts. | | `proxyman-debugging-tools` | Fetch current official docs and deeply guide Breakpoint, Map Local/Remote, Scripting, Compose/Repeat, Protobuf, Network Conditions, Reverse Proxy, and TLS Key Logging with exact interface boundaries. | | `proxyman-license-management` | Activate/unlink the current device and manage remote devices, seats, transfers, and renewal safely. | | `proxyman-cli` | Discover installed CLI syntax and automate proxy, MCP, configuration, logs, certificates, and rules. | | `proxyman-https-capture` | Configure and verify HTTPS capture for devices/runtimes/containers and choose or integrate Atlantis for controlled apps. | ### Routing * Proxyman is absent: `proxyman-download-setup`. * The user asks where an App Setting lives, what it changes, why it is locked, or wants a Settings audit/change: `proxyman-app-settings`. * The user needs generated/custom root trust, custom server/client certificates, Debug Mode, Reset Network Proxy, or Factory Reset: `proxyman-certificates-recovery`. * Proxyman is installed but MCP tools are missing: `proxyman-mcp-setup`. * The user wants the agent to inspect/change Proxyman through MCP: `proxyman-traffic-debugging`. * The user asks how a Proxyman tool works or needs the latest official guide: `proxyman-debugging-tools`. * The user needs license activation, unlink, remote revoke, or License Manager: `proxyman-license-management`. * The user wants a shell command or scripted operation: `proxyman-cli`. * The user needs traffic from a device, emulator, app, runtime, or container to appear and decrypt: `proxyman-https-capture`. Skills can work together. For example, use HTTPS Capture to configure an Android emulator, then Traffic Debugging to verify its flows and create a Map Local rule. ### Requirements And Safety * Proxyman must be installed and running before operational [MCP](https://proxyman.com/docs/mcp) tools work. * Turn on **Enable MCP Server** in Settings > MCP, or use the installed [`proxyman-cli mcp`](https://proxyman.com/docs/command-line) command after reading the help for your version. * Configure agents with Proxyman's bundled stdio bridge, not a fixed HTTP URL or the main app executable. * Treat live `tools/list`, resources/prompts discovery, and installed CLI help as authoritative for schemas and syntax. * Treat the installed Settings UI as authoritative for preferences; the reviewed MCP server is not a generic App Settings API. * Treat certificate/private-key imports, trust changes, Debug Mode output, and Factory Reset as sensitive; preserve required sources and backups outside Proxyman-managed folders before destructive recovery. * Keep **Redact Sensitive Data Before Sending to AI** enabled unless raw data is explicitly required and approved. * MCP preview redaction does not sanitize original HAR/Proxyman log exports. * Fetch `https://proxyman.com/docs/llms.txt` and its linked Markdown pages when current product behavior matters. * License keys, TLS session-key logs, portal access links, proxy credentials, certificate passwords, and captured secrets must not be stored in skills, commands, logs, or reports. ### Plugin Packaging The skill bundle is self-contained and can be placed under a Codex plugin's `skills/` directory. The plugin still needs to configure or document the local Proxyman MCP bridge separately; packaging these skills does not embed the Proxyman app, bridge executable, license, or a running MCP connection. The production Proxyman plugin is available on [ChatGPT](https://chatgpt.com/plugins/plugins_6a88afab118c8191970bbc714223ff14). The publishable plugin source is available at `plugins/proxyman` in the GitHub repo. It is a skills-only package with a public-ready manifest and Proxyman brand asset. See `SUBMISSION.md` in the repo for the marketplace listing, starter prompts, reviewer tests, release notes, and the remaining OpenAI Platform submission checks. ## Learn more * [How to use Proxyman MCP with Codex and Claude Code](https://proxyman.com/posts/how-to-use-proxyman-mcp-with-codex-and-claude-code) --- Source: https://proxyman.com/docs/security-compliance # Security Compliance > Proxyman is SOC 2 Type 2 compliant. Learn what the audit covers, what it means for customers and resellers, and where to find Proxyman security policies. ## Exciting News: Proxyman Achieves SOC 2 Type 2 Compliance! ![Proxyman app icon next to the AICPA SOC badge with the text Proxyman is now SOC-2 Compliant](https://proxyman.com/docs/assets/Frame%208.jpg) _Proxyman is now SOC 2 Compliant_ ## What is SOC 2 Type 2 Compliance? SOC 2 is a strict audit by the AICPA. A Type 2 report confirms that our security controls are well designed and that they worked well over a period of time. The audit checks five key criteria: * **Security**: Protects against unauthorized access. * **Availability**: Ensures system availability for use. * **Processing Integrity**: Guarantees complete and accurate processing. * **Confidentiality**: Safeguards confidential information. * **Privacy**: Handles personal data per our privacy policy. ## Why SOC 2 Type 2 Compliance Matters Strong security is essential. For a debugging proxy tool that handles sensitive data, SOC 2 compliance: * Validates security controls. * Shows commitment to data protection. * Offers independent verification. * Demonstrates adherence to industry standards. ## What Does This Mean for You? ### **As a Customer** * **Enhanced Security**: Your data has strong, verified protection. * **Privacy Assurance**: Your information is handled responsibly. * **Transparency**: Security practices are verified. * **Trust**: Confidently use Proxyman in enterprises. ### **As a Reseller** * **Credibility**: Assure customers of our security. * **Enterprise-Ready**: Easily recommended to security-focused organizations. * **Compliance**: Meet vendor assessment needs. * **Documentation**: Access for sales support. > **Note:** A SOC 2 Type 2 report checks how controls worked during an audit period. Normal Proxyman captures are stored on your device. Please review optional features such as [Share Log online](https://proxyman.com/docs/team-workspace/share-log-online) and [Team Workspace](https://proxyman.com/docs/team-workspace/team-workspace) under your company policy before you use them. ## Privacy Statement You can find our [Privacy Policy](https://proxyman.com/privacy). ## What's Next? This milestone is the first step. Our focus includes: * Maintaining SOC 2 Type 2 compliance. * Conducting regular audits. * Continuously improving security practices. For more about our security and privacy policies, see our [Privacy Policy](https://proxyman.com/privacy), [Terms of Service](https://proxyman.com/terms-of-use), and [SDLC Policy](https://proxyman.com/software-development-lifecycle-policy). Questions? Reach us at support@proxyman.com ## Learn more * [Proxyman SOC 2 Type II Compliance](https://proxyman.com/posts/2024-12-21-Proxyman-is-now-SOC-2-Type-1-Compliant) --- Source: https://proxyman.com/docs/team-workspace/team-workspace # Team Workspace > Use Proxyman Team Workspace to invite teammates, give them Admin or Developer roles, track seat usage and share licenses and logs with your team. ## 1. What’s it? Team Management is the workspace feature that lets you manage who can access your workspace, what role they have, and how many seats you’re using. > **Note:** This feature is only available for the **Team Subscription plan** (seat-based) ![Proxyman Workspace Team page with seat usage, team members and their admin or developer roles](https://proxyman.com/docs/assets/Screenshot%202026-01-20%20at%2015.48.56.jpg) ### Roles (role-based access) #### Admin * Full access to everything: licenses, logs, team, and workspace settings * Can view seat usage, invite members, bulk invite, change roles, remove members, and revoke invitations * Only admins can access the Team page #### Developer * Can view the license key and all shared logs within the team * Cannot access the Team management page (admin-only) *** ## 2. Benefit * Centralized access control: keep workspace access managed in one place. * Safer collaboration: assign roles so teammates only have the permissions they need. * Seat visibility: see used / total seats, pending invitations, and remaining capacity. * Fast onboarding: invite one person or bulk invite up to 50 emails at a time. * Fewer mistakes: invitations expire in 24 hours, and bulk invite automatically skips emails that can't be invited (for example, no seats left, already registered, or already invited). *** ## 3. How to use it ### Open the Team page (admin-only) 1. Sign in to [Proxyman Workspace](https://workspace.proxyman.com) as an Admin. 2. Go to Settings → Team. If you’re not an admin, you’ll see an “Admin access required” message. ### Check seat usage (Team plan) * Review the Seat Usage card: * Used / Total seats * Available seats * Pending invitations * When seats are low or full, the UI warns you before inviting. ### Invite a single member 1. Click Invite Member. 2. Enter the teammate’s email. 3. Choose a role: * Developer (license key + shared logs) * Admin (full access) 4. Click Send Invitation. Notes: * Invitation links expire in 24 hours. * If there are 0 seats available, inviting is blocked and you’ll be prompted to add seats. ![Invite Team Member dialog with an email address field and the Developer role selected](https://proxyman.com/docs/assets/Screenshot%202026-01-20%20at%2015.52.15.png) ### Bulk invite (up to 50) 1. Click Bulk invite. 2. Paste emails comma-separated (max 50). 3. Choose a role for all invited emails. 4. Click Schedule invitations (sent shortly to avoid spam filters). After scheduling, the UI shows how many were scheduled and which ones were skipped (with reasons like no seats, already registered, already invited). ### Change a member’s role (admin-only) 1. In Team Members, open the role dropdown for a member. 2. Select Developer or Admin. The current user’s own role is displayed but not editable from this page. ### Remove a team member (admin-only) 1. In Team Members, open the actions menu for a member. 2. Click Remove member and confirm. Result: the member loses access to all workspace resources. ### Revoke a pending invitation (admin-only) 1. In Pending Invitations, click the trash icon for an invitation. 2. Confirm Revoke. Result: the invite link becomes unusable. ### Buy more seats (Team plan) * Click Buy More Seats (or Extend Seats when you hit seat limits). * Complete the seat upgrade flow. * The page refreshes seat usage and team data after success. ![Extend Subscription Seats dialog to add seats, with current and new seat totals and the prorated charge](https://proxyman.com/docs/assets/Screenshot%202026-01-20%20at%2015.53.04.png) Your team can also share captured logs in the workspace. See [Share Log online](https://proxyman.com/docs/team-workspace/share-log-online). --- Source: https://proxyman.com/docs/team-workspace/share-log-online # Share Log online > Share Proxyman logs and HAR files with your team online. Upload from the Proxyman app or Workspace, add notes, redact secrets and control who can view. ## 1. What’s it? Proxyman HTTP Logs is the workspace feature that lets you upload, store, and share Proxyman HTTP capture files so you (and your team) can review issues with the same context. Supported uploads: * .proxymanlogv2, .proxymansessionv2, .har * Max file size: 50 MB per upload ### Upload from Proxyman app 1. Make sure you've already logged into your [Team Workspace](https://proxyman.com/docs/team-workspace/team-workspace) 2. In the Proxyman app -> Select the requests that you'd like to share -> Right-Click -> Export -> Share Online… * Redact Sensitive Data: Remove tokens, passwords, cookies, and auth headers before sharing * Add Note * Change the name of the log * Choose who can see this log 3. Click Share to share it to your workspace ![Proxyman Share Log Online sheet with Redact Sensitive Data, an optional note and access settings](https://proxyman.com/docs/assets/Screenshot%202026-01-24%20at%2013.49.44.png) _Share Log Online in the Proxyman macOS app_ ### Upload from Workspace website 1. Visit [https://workspace.proxyman.com/logs](https://workspace.proxyman.com/logs) -> Click on the Browse File button -> Select the Proxyman Log that you've already exported from your Mac. > **Note:** To export a Proxyman Log in the Proxyman app: Select the requests that you'd like to export -> Right-Click -> Export -> as Proxyman Log… 2. Add an optional note (Markdown supported) ![Edit Note dialog in Proxyman Workspace with a Markdown editor and a Preview tab](https://proxyman.com/docs/assets/Screenshot%202026-01-20%20at%2016.26.43.png) 3. Set sharing permissions ### Sharing & permissions model Each log can be shared as: * **Private**: only permitted viewers can access (default when no sharing is set) * **Team**: all workspace members can view * **Specific users**: only selected teammates can view (by email) * **Public**: anyone with the share link can view Important rules: * A log has a share link: /shared/\ * Only the uploader can change sharing settings for that log (others can view if they have access, but can’t change permissions) #### Roles (role-based access) * Admin * Full workspace access (licenses, logs, settings, team) * Can view logs they have access to * Can manage sharing only for logs they uploaded (uploader-only rule still applies) * Developer * Can view logs shared with them (via Team, Specific users, or Public link) * Can upload logs and manage sharing only for logs they uploaded > **Note:** Team Subscription plan note: “Team” and “Specific users” sharing is designed for Team-plan workspaces where you have teammates in the workspace (seat-based access). *** ## 2. Benefit * Fast collaboration: upload a capture once, share it with your team instantly. * Clear context: add a note (Markdown supported) to explain what to look for. * Flexible sharing: keep logs private, share to the whole team, specific teammates, or publicly via link. * Simple organization: see filename, size, uploader, sharing state, and relative upload time in one table. * Storage safety: when quota is exceeded, the UI tells you how to recover (delete old logs or contact support to upgrade quota). ![Your Shared Logs table with file name, note, size, uploader, sharing state and created time](https://proxyman.com/docs/assets/Screenshot%202026-01-20%20at%2016.32.57.png) *** ## 3. How to use it ### 1. Upload a log You can upload in two ways: * Click “Upload Log” / “Browse Files” * Drag & drop the file into the drop zone The page validates: * File type (.proxymanlogv2, .proxymansessionv2, .har) * File size (≤ 50 MB) ### 2. Add a note (optional) After upload completes, a dialog opens to add a note: * Supports basic Markdown (bold/italic/code/lists/links) * Has a character limit (the UI will block saving if you exceed it) * You can preview the rendered Markdown before saving ### 3. Configure sharing After the note dialog closes, the Share Log dialog opens. You can: * Toggle Public Access (anyone with the link can view) * Toggle Team Access (all team members can view) * Add Specific Users (only teammates in the workspace; you must invite them first) Then click Save Changes. Notes: * You can only add emails that belong to teammates already in your workspace * Only the uploader can change these settings ### View, download, copy link, or delete In Your Shared Logs, each log supports: * Open the log details: click the filename (goes to /logs/\) * Manage Sharing * Add/Edit Note * Download * Copy Share Link (copies /shared/\) * Delete (with confirmation; cannot be undone) ### If the storage quota is exceeded If you hit the workspace storage limit during upload, you’ll see Storage Quota Exceeded with options to: * Delete old log files to free space * Contact support@proxyman.com to upgrade storage quota ## Learn more * [How to Report API Bugs with a Proxyman Log or HAR File](https://proxyman.com/posts/2019-07-06-How-I-use-Proxyman-to-report-bugs-more-effectively) --- Source: https://proxyman.com/docs/proxyman-ios/vpn-and-proxyman-certificate # Proxyman for iOS > Proxyman for iOS captures and decrypts HTTP and HTTPS traffic on your iPhone or iPad with a local VPN, with no Mac needed. See features and setup. ## 1. Proxyman for iOS ### Features * ✅ Capture all HTTP/HTTPS traffic from your iOS devices. No Mac required. * Proxyman for iOS is a **standalone** app. It works **independently** of Proxyman for macOS. * View HTTP/HTTPS requests and responses in plain text. * Face ID and Passcode to protect your sensitive data. * Share logs to Proxyman for macOS. * Split View (two side panels) on iPad. * Debugging tools: Map Local, Breakpoint, Block List, SSL Proxying List, No Caching. * And more... ### Download * App Store: [https://apps.apple.com/us/app/proxyman/id1551292695](https://apps.apple.com/us/app/proxyman/id1551292695) * Requires iOS 17 or later ### Screenshots ![Proxyman for iOS on iPhone: domain list, request details and response headers of a captured POST request](https://proxyman.com/docs/assets/Screenshot%202023-06-01%20at%2015.28.38.jpeg) _Capture iPhone traffic and inspect requests and responses_ ![Proxyman for iOS JSON body preview next to the same request shared to Proxyman for macOS](https://proxyman.com/docs/assets/Screenshot%202023-06-01%20at%2015.28.42.jpeg) _Preview a JSON body and share it to Proxyman for macOS_ ## 2. Proxyman VPN ### How does it work? Proxyman for iOS creates a local VPN on your device. Then it sends all traffic from your iOS device through a local Man-in-the-Middle server. ### What data does Proxyman use? 1. **HTTP/HTTPS Request and Response data** Proxyman captures and decrypts HTTP/HTTPS data (including headers, body, URL, host, etc.) to show it in plain text. 2\. **Device Name** Proxyman uses it to generate a self-signed Root Certificate. Proxyman does not use pre-generated or shared certificates. > **Note:** Proxyman records the request/response data and stores it in a **local SQLite database** on your iOS device. > > Proxyman **does not send** your data to any remote servers or third parties. > > Your data always remains **private** to you. ## 3. Activate Premium Proxyman for iOS If you have a valid macOS license, you can activate Premium Proxyman for iOS. One seat covers 2 iOS devices. To activate: download Proxyman for iOS from the App Store -> open the **More** tab (bottom-right of the tab bar) -> **Face ID & Passcode** -> **Unlock** -> enter your license key. ## Learn more * [Capture and inspect HTTPS traffic from iPhone](https://proxyman.com/posts/2021-10-17-Getting-Started-With-Proxyman-For-iOS) --- Source: https://proxyman.com/docs/proxyman-ios/map-local-for-ios # Map Local for iOS > Use Map Local in Proxyman for iOS to return a custom status code, headers and body for matching requests, so you can mock APIs right on your iPhone. ## What's it? Map Local is a tool that helps iOS developers: * Map a URL to a pre-defined response. You can quickly test a new response without waiting for the real endpoint from your backend server. * Modify the status code, headers, and body. ![Proxyman for iOS flow list, request details executed by Map Local, and the response body replaced by a local file](https://proxyman.com/docs/assets/image%20(13).png) _Map Local on iOS_ ## Tutorial Check out the Map Local for iOS tutorial: - [Map Local for iOS Tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/map-local-for-ios-tutorial) --- Source: https://proxyman.com/docs/proxyman-ios/breakpoint-for-ios # Breakpoint for iOS > Use Breakpoint in Proxyman for iOS to pause a request or response on your iPhone and edit its URL, method, status code, headers and body on the fly. ## 1. What's it? Breakpoint is a tool that helps developers: * Modify the request content: URL, method, headers, and body * Modify the response content: status code, headers, and body on the fly, without Proxyman for macOS. ![Proxyman for iOS Breakpoint Request Editor with method, URL, header, query and body of a paused POST request](https://proxyman.com/docs/assets/1%20(1).png) _Breakpoint Request Editor on iOS_ ## 2. Tutorial Check out the Breakpoint for iOS tutorial. - [Breakpoint for iOS Tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/breakpoint-for-ios-tutorial) --- Source: https://proxyman.com/docs/proxyman-ios/tutorial-for-ios # Tutorial for iOS > Step-by-step tutorials for Proxyman for iOS: mock responses with Map Local and edit requests and responses with Breakpoint on your iPhone. Learn how to use the debugging tools in Proxyman for iOS to change HTTP/HTTPS traffic on your iPhone. - [Map Local for iOS Tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/map-local-for-ios-tutorial) - [Breakpoint for iOS Tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/breakpoint-for-ios-tutorial) --- Source: https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/map-local-for-ios-tutorial # Map Local for iOS Tutorial > Step-by-step tutorial: mock HTTP/HTTPS responses on your iPhone with Proxyman for iOS Map Local and change the status code, headers and body. ## Manipulate HTTP(s) responses on iPhone with Proxyman Map Local Since version 2.0.0, Proxyman for iOS has the Map Local tool. It lets you use the content of a local file as the response to requests that match your rules. Map Local helps you develop faster. You can quickly test edge cases without changing the data on your server. It's also a must-have tool for QA and developers who want to test the app's behavior with different responses. Some testing scenarios: * Define a response and use it for matching requests. * Quickly try new parameters in responses. * Test the app's behavior with different parameters in the responses. * Test the UI layout with unusual content. * Quickly reproduce a bug with specific parameters in responses. * Mock an API with a local file. It's useful when you want to try test APIs that are not in production yet. ## Prerequisites * Download the latest version of Proxyman from the App Store: [https://apps.apple.com/us/app/proxyman/id1551292695](https://apps.apple.com/us/app/proxyman/id1551292695) * Install and trust the Proxyman certificate on your iOS device. If you're new to Proxyman, follow [Capture and inspect HTTPS traffic from iPhone](https://proxyman.com/posts/2021-10-17-Getting-Started-With-Proxyman-For-iOS) to start capturing HTTP traffic on your iPhone. ## Create Map Local Rules There are 2 ways to create a Map Local rule: 1. From the More tab * Go to the **More** tab → **Map Local** → tap the **+** button. * Fill in the fields for the rule: Name, URL, Method, and whether to include subpaths. 2. From the context menu * Long-press the request → **Add to Map Local**. * Proxyman fills in all fields of the rule from the selected request. ![Proxyman for iOS context menu with Add to Map Local, which opens a Map Local Editor filled from the request](https://proxyman.com/docs/assets/image%20(14).png) _Create a Map Local rule from a request_ ### Modify Header, Status Code and Body In the Map Local Editor, you can change the headers, status code, and body. If you replace the body with a new data type, Proxyman detects the Content-Type and updates the headers for you. ## Manipulate Response with Map Local Tool ![Proxyman for iOS Map Local Editor with status 201 Created next to the enabled Map Local rule list](https://proxyman.com/docs/assets/image%20(12).png) _Enable Map Local and the rule_ You're all set. Make another request to see how it works. If the URL of an incoming request matches a **pre-defined matching rule** and the local file is valid, Proxyman replaces the response body of that request with the content of the local file. If a request doesn't match any rule, the response from the server stays the same. ![Proxyman for iOS flow list, request details executed by Map Local, and the response body replaced by a local file](https://proxyman.com/docs/assets/image%20(13).png) _The response is modified by Map Local_ Nicely done! In the flow list, a small blue icon shows that this flow has been modified. The response content has been replaced with the local file. ## What's next Map Local lets you try different responses to test the layout or content on your device. But it can only modify the response. If you'd like to modify the request too, check out the [Breakpoint for iOS tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/breakpoint-for-ios-tutorial). Breakpoint lets you change both the request and the response on the fly without changing any logic in your app. --- Source: https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/breakpoint-for-ios-tutorial # Breakpoint for iOS Tutorial > Step-by-step tutorial: use Proxyman for iOS Breakpoint to pause traffic on your iPhone and edit the URL, method, headers, body and status code. ## Modify HTTP(s) Request & Response on your iPhone with Proxyman Breakpoint Since version 2.0.0, Proxyman for iOS lets you change request and response data on the fly, without changing any logic in your app. This short tutorial shows how to modify HTTP(s) requests and responses on iOS devices with the Proxyman Breakpoint tool. For example: * Modify the request URL (including the scheme, host, path, port) and HTTP method * Modify HTTP headers of the request or response * Modify the query of a request * Modify the HTTP body of the request or response * Modify the response HTTP status code ## Prerequisites * Download the latest version of Proxyman from the App Store: [https://apps.apple.com/us/app/proxyman/id1551292695](https://apps.apple.com/us/app/proxyman/id1551292695) * Install and trust the Proxyman certificate on your iOS device. If you're new to Proxyman, follow [Capture and inspect HTTPS traffic from iPhone](https://proxyman.com/posts/2021-10-17-Getting-Started-With-Proxyman-For-iOS) to start capturing HTTP traffic on your iPhone. ## Create Breakpoint Rules There are 3 ways to create a Breakpoint rule: 1. From the More tab * Go to the **More** tab → **Breakpoint** → tap the **+** button. * Fill in the fields for the rule: Title, Method, Matching URL, and whether to include subpaths. * Choose whether the rule applies to requests, responses, or both. 2. From the "Waiting Breakpoints" screen * Tap the Waiting Breakpoint icon → **Create Breakpoint Rule**. * Then fill in the rule (same as the previous option). 3. From the context menu * Long-press the request → **Add to Breakpoint List**. * Proxyman fills in all fields of the rule from the selected request. ![Proxyman for iOS context menu with Add to Breakpoint List, which opens a rule filled with httpbin.org](https://proxyman.com/docs/assets/image%20(4).png) _Create a Breakpoint rule from a request_ In this example, the Breakpoint rule applies to both requests and responses. Let's make a request to see how it works. ## Modify HTTP(s) Requests When you make a request that matches the URL, Proxyman pauses it and shows that there are waiting breakpoints. On the Home screen, tap the small icon to see the waiting breakpoint list. Then select a breakpoint to start editing the request. ### Modify URL + Method You can change the HTTP method, URL, and query. The URL updates when the queries change, and the other way around. ![Proxyman for iOS Breakpoint Request Editor with an edited URL query and the HTTP method menu open](https://proxyman.com/docs/assets/image%20(18).png) _Modify the URL and HTTP method_ ### Modify Body If you replace the body with a new data type, Proxyman detects the Content-Type and updates the headers for you. ## Execute, abort, continue Breakpoint When you're happy with the change, execute the request or response from the menu at the top right. To keep the original request, use **Continue**. To cancel it, use **Abort**. Since the Breakpoint rule applies to both the request and the response, the response is added to the waiting breakpoint list after you tap **Execute**. Now you can change the HTTP status code, update headers, or replace the body of the response (the same way as modifying the request). Nicely done! In the flow list, a small blue icon shows that this flow has been modified. Both the request and the response have been updated as expected. ![Proxyman for iOS request details executed by Breakpoint and the new response body](https://proxyman.com/docs/assets/image%20(9).png) _The request and response are modified by Breakpoint_ **NOTES**: * When you create a new rule, both the Breakpoint tool and the rule are enabled by default. You can switch them on or off as needed. * Make sure the VPN, the Breakpoint tool, and the Breakpoint rule are all enabled so that Breakpoint can work. * If the first rule matches the request or response, other rules are not applied. * While you edit the request, the Response tab is disabled. While you edit the response, the Request tab is read-only. ## What's next Breakpoint lets you modify the request and response on the fly, but it needs a lot of manual work. To automate it, check out the [Map Local for iOS tutorial](https://proxyman.com/docs/proxyman-ios/tutorial-for-ios/map-local-for-ios-tutorial) to map a local file as a response automatically. --- Source: https://proxyman.com/docs/debug-devices/macos # macOS > Install and trust the Proxyman CA certificate on macOS, verify HTTPS capture, or use manual Keychain setup when automatic installation fails. To inspect HTTPS traffic on your Mac, install and trust the Proxyman CA certificate, then enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain you want to inspect. Start with automatic installation below, or use Manual Mode if you need to manage trust in Keychain Access yourself. ## Install & Trust Proxyman Certificates on your Mac To intercept encrypted HTTPS messages (request or response), you have to install the **Proxyman CA Certificate** on your current machine. This step is also required for iOS devices, Android devices, iOS simulators, Java VMs, and Firefox. > **Note:** The Proxyman Certificate is a self-signed certificate that is generated on your machine. Proxyman never stores or sends any personal data to Proxyman's servers or to third parties. > > Please check out the [Privacy Statement](https://proxyman.com/privacy) to see what data Proxyman collects and what it does not. > > If you'd like to generate a certificate on your machine yourself and add it to Proxyman, please check out the [Custom Certificate Doc](https://proxyman.com/docs/advanced-features/custom-certificates#6-how-to-generate-self-signed-certificates-for-custom-root-certificate-that-comply-with-new-apples-security-requirements). > **Note:** Proxyman's certificate is stored locally at **\~/Library/Application\ Support/com.proxyman.NSProxy/app-data/** ## 1. Automatic mode (recommended) Proxyman can **automatically** install and trust the certificate in Keychain. Follow these steps: 1. Open the **Certificate** menu 2. Select **Install Certificate on this Mac…** 3. In the **Automatic** tab, click **Install & Trust Certificate** and enter your Mac's password (root privileges) 4. Verify the status: ✅ `Installed & Trusted` in the button (If not, try the Manual tab, or contact us for further support) 5. Done :white\_check\_mark: To verify capture, make a new HTTPS request from your browser with Proxyman running and SSL Proxying enabled for that domain. Confirm that you can read the request and response. If nothing appears, use the [missing-traffic checklist](https://proxyman.com/docs/troubleshooting/i-couldnt-see-any-traffics-on-proxyman); if certificate installation fails, continue with Manual Mode below. ![Proxyman Mac Setup Guide, Automatic tab, with the certificate shown as Installed & Trusted](https://proxyman.com/docs/assets/proxyman-mac-setup-guide-automatic.jpg) _Certificate installed and trusted_ > **Note:** **Automatic mode** requires **root privileges** to run the installation script. If you're not sure, please consider using Manual mode. ### How does it work? In automatic mode, Proxyman performs two steps: 1. Generate a local Proxyman Certificate at `~/Library/Application\ Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem` 2. Install and trust the certificate in the System keychain. It requires root privileges to run the following command: ```bash sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/Library/Application\ Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem ``` ## 2. Manual Mode (Advanced) Manual mode gives advanced users more control if they want to install and trust the certificate themselves. 1. Open the **Certificate** menu 2. Select **Install Certificate on this Mac…** -> Select the **Manual** tab 3. Click the **Generate and Add…** button (Proxyman generates the certificate locally and adds it to Keychain, but does not trust it. No password required) 4. In some cases, macOS asks which keychain to use -> Select **System Keychain** 5. Open the Keychain Access app on your Mac -> Search "Proxyman CA" -> Open it -> Select "Always Trust" -> Close the window and save > **Note:** If you've done it correctly, Proxyman will display the " ✅ Installed and Trusted" status. ![Proxyman Mac Setup Guide, Manual tab, with steps to set Proxyman CA to Always Trust in Keychain Access](https://proxyman.com/docs/assets/proxyman-mac-setup-guide-manual.jpg) _Manual mode: trust the certificate in Keychain_ > **Note:** If you'd like to use your own custom Root Certificate, please check out the [Custom Certificate Doc](https://proxyman.com/docs/advanced-features/custom-certificates#6-how-to-generate-self-signed-certificates-for-custom-root-certificate-that-comply-with-new-apples-security-requirements) If you're not sure how to trust the certificate in the Keychain Access app, open the Terminal app and run this command: ```bash sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/Library/Application\ Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem ``` > **Note:** Make sure that you **delete the Proxyman Certificate in the Keychain Access app** if you're not using Proxyman anymore. If not, anyone who has the Proxyman Certificate can intercept HTTP/HTTPS requests from your Mac. ## 3. Uninstall Proxyman Certificate 1. Open the **Certificate** menu 2. Select **Reset all Proxyman Certificates** 3. Enter your Mac password and done ## Video [Video: Capture HTTP and HTTPS traffic with Proxyman](https://proxyman.com/videos/capture-http-https-traffic) (25 seconds) --- Source: https://proxyman.com/docs/debug-devices/ios-device # iOS Device > Capture iPhone and iPad HTTP/HTTPS traffic with Proxyman on your Mac: set the Wi-Fi proxy, then install and trust the Proxyman certificate on the device. To capture traffic from an iPhone or iPad, route its Wi-Fi traffic through Proxyman on your computer. HTTPS inspection also requires installing the Proxyman certificate and explicitly trusting it on the device. These are separate steps. Keep Proxyman running and connect the device to a network that can reach your computer. Use the computer IP address and Proxyman port shown in the setup guide, rather than the device IP address. Open the physical-device setup guide in Proxyman: * **Certificate** **Menu** -> **Install Certificate on iOS -> Physical Devices...** > **Tip:** This setup guide works with all real physical devices, including iPhone, iPad, Apple Watch, Apple TV, and Apple Vision Pro. ## iOS Setup Guide ![Proxyman iOS Setup Guide with the Wi-Fi proxy server and port, proxy.man/ssl link, and install and trust steps](https://proxyman.com/docs/assets/proxyman-ios-setup-guide.jpg) _iOS Setup Guide for physical devices_ Follow these steps: 1. Install the **Root Proxyman Certificate** on your Mac: You can follow the [macOS Guide](https://proxyman.com/docs/debug-devices/macos). 2. On your iOS device, open the Settings app -> Wi-Fi -> Select the current Wi-Fi -> Configure the HTTP Proxy with the values in this table. | Name | Value | | -------------- | ------------------------------------------------- | | Server IP | Your Mac's current IP address | | Port | The current port of Proxyman: 9090 is the default | | Authentication | No | > **Note:** If you're using any **VPN apps** on macOS or iOS devices, please close all of them, as they conflict with the HTTP Proxy configuration. 3\. Open [http://proxy.man/ssl](http://proxy.man/ssl) or [http://cert.proxyman.io](http://cert.proxyman.io/) in a **Safari Private tab** on your iOS device to download the Proxyman Certificate. > **Note:** **http://proxy.man/ssl** and **http://cert.proxyman.io** are local websites, served by the HTTP server inside Proxyman. If you can't open them, forget the Wi-Fi network, reconnect, and make sure the Proxyman app is open. > > If you still can't access it, please open a support ticket in the [Proxyman GitHub repo](https://github.com/ProxymanApp/Proxyman). 4\. From iOS 10.3, you have to explicitly install and trust the Proxyman CA in the Settings app. #### **Install Proxyman CA** * **iOS ≥ 12.2**: On your iPhone -> Open the Settings app > Profile Downloaded > Select Proxyman CA > Install #### Trust Proxyman CA Installing the profile does not enable full trust by itself. Complete this step before testing HTTPS traffic: * Settings app > General > About > Certificate Trust Settings > Switch ON Proxyman CA. ![iOS Install Profile screen for Proxyman CA and the Certificate Trust Settings switch turned on](https://proxyman.com/docs/assets/install_and_trust_proxyman_certificate.png) > **Note:** Please make sure you **install** and **trust** the Proxyman CA on your iOS device. If you have any problem, email us at **support@proxyman.com** or open an issue on [**GitHub**](https://github.com/ProxymanApp/Proxyman) > **Note:** After setup, enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain and make a new request. If no traffic appears, verify the Wi-Fi proxy IP and port, network connectivity, and VPN settings using the [device connection troubleshooting guide](https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy). If requests appear but HTTPS fails, recheck certificate installation and trust. > **Note:** Make sure that you **delete the certificate on your iPhone** when you're not debugging with Proxyman. If not, your HTTP/HTTPS requests can be intercepted and leak your sensitive data. ## Tutorial See detailed steps on how to [debug an application on iOS device](https://proxyman.com/posts/2019-06-16-How-I-use-Proxyman-to-see-HTTP-requests-responses-on-my-iPhone) with Proxyman. ### Tired of manual config? We understand that manually overriding the HTTP Proxy and installing and trusting Proxyman Certificates is painful. Check out Atlantis, a native iOS framework that does it for you automatically. - [Atlantis for iOS](https://proxyman.com/docs/atlantis/atlantis-for-ios) ## Flutter app? You might not be able to see the network traffic in Proxyman if your app is a Flutter app. Flutter does not use the system-level proxy, so its requests do not go to Proxyman. To fix it, you must configure the HTTP client in your code to use a proxy. See the [Flutter guide](https://proxyman.com/docs/debug-devices/flutter) for the code samples. You can also follow the solution "Getting Charles to work with Flutter" in [https://flutterigniter.com/debugging-network-requests/](https://flutterigniter.com/debugging-network-requests/) To find your local IP, go to the Certificate menu -> Install Certificate on iOS -> Physical Devices… and get the Server IP and Port. ## Learn more * [How to capture HTTP/HTTPS traffic from iPhone on iOS 26 or iPadOS 26](https://proxyman.com/posts/how-to-capture-https-iOS-26-update-2025) * [How to capture HTTPS traffic from an iOS app with a company VPN](https://proxyman.com/posts/capture-https-ios-app-with-company-vpn) * [Capture HTTPS traffic from iPhone and iPad with Proxyman](https://proxyman.com/iphone-device) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/ios-simulator # iOS Simulator > Capture iOS Simulator HTTP/HTTPS traffic with Proxyman on macOS, using automatic certificate setup, manual installation, and missing-traffic checks. Use Proxyman on your Mac to capture and inspect HTTP/HTTPS requests from iOS Simulator. Start with automatic certificate installation; use the manual steps below if installation fails. Before you start, install Xcode and open the simulator you want to debug at least once. Keep Proxyman running while you reproduce requests in your app. For HTTPS inspection, install and trust the certificate, then enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain. Open the simulator setup guide in Proxyman: * **Certificate** **Menu** -> **Install Certificate on iOS -> Simulators** ## Video [Video: Capture HTTPS traffic from an iOS Simulator](https://proxyman.com/videos/ios-simulator) (32 seconds) [Capture HTTPS from a native iOS app on the iOS 26 Simulator with Xcode 26](https://www.youtube.com/watch?v=THzb2e9hoGo) ## 1. iOS Simulator Setup Guide ![Proxyman iOS Simulators Setup with three steps: certificate Installed & Trusted, Prepare Simulators, and Reboot](https://proxyman.com/docs/assets/proxyman-ios-simulators-setup.jpg) _iOS Simulators Setup_ > **Note:** It works for iOS, iPadOS, tvOS, watchOS and visionOS. The setup guide has three steps: 1. Install the **Root Proxyman Certificate** on your Mac: You can follow the [macOS Guide](https://proxyman.com/docs/debug-devices/macos). 2. Install the Proxyman Certificate on all available simulators that you have opened at least once (click **Prepare Simulators**). 3. **Reboot the simulators**: Proxyman reboots all simulators, so they load the new certificate. > **Note:** From Proxyman 2.19.0+, Proxyman uses the [simctl](https://nshipster.com/simctl/) command line to perform these tasks. > > **simctl** comes with Xcode. It is more modern and reliable than the legacy approach (custom Python scripts). > **Note:** This step only installs the certificate on simulators that you have opened at least once. > > For instance, if you would like to debug on the iPhone X Simulator, please make sure to **open** the iPhone X Simulator first, then **install** the certificate in Step 2. ### Xcode Preview (SwiftUI) If you're using Xcode Previews for SwiftUI, you can install the certificate into the Xcode Preview simulator: 1. Open Xcode with the SwiftUI preview canvas. 2. Open Proxyman -> Certificate menu -> Install Certificate on iOS -> Simulators 3. In Step 2, click the ↓ button (next to the Prepare Simulators button) -> Install to Xcode Preview (SwiftUI) You can read more in [GitHub issue #1568](https://github.com/ProxymanApp/Proxyman/issues/1568#issue-1610877870). ### Manually Install In Proxyman v4.16.0 or later, you can manually install the certificate on your iOS Simulator in case the automatic solution doesn't work. 1. Certificate menu -> Install Certificate on iOS -> Simulators 2. In Step 2, click the ↓ button (next to the Prepare Simulators button) -> Install Manually… ![Proxyman iOS Simulators Setup with the Prepare Simulators menu open and Install Manually selected](https://proxyman.com/docs/assets/Screenshot%202024-11-01%20at%2020.14.39.jpg) _Install the certificate manually_ 3. Drag and drop the certificate onto your iOS Simulator ![Proxyman sheet with a draggable Proxyman Certificate icon and steps to trust it in the simulator](https://proxyman.com/docs/assets/Screenshot%202024-01-07%20at%2014.43.13.png) _Drag the certificate onto the simulator, then trust it_ 4. Open your iOS Simulator -> Settings app -> General -> About -> Certificate Trust Settings -> Find the Proxyman CA certificate and switch it ON 5. Done ## 2. Troubleshooting If the request list is empty, first check recording, filters, and proxy settings using the [missing-traffic checklist](https://proxyman.com/docs/troubleshooting/i-couldnt-see-any-traffics-on-proxyman). If requests appear but HTTPS fails, check certificate installation and SSL Proxying. The sections below cover installation errors and cached requests. ### 1. Unable to install the Certificate If you get errors when you click the button in Step 2, open Xcode -> Settings -> Locations tab -> Select your Xcode in Command Line Tools. ### 2. Get SSL Error from HTTPS Response * Open the Settings app -> General -> About -> Certificate Trust Settings and verify that the Proxyman Certificate is installed and trusted. If it's not installed: * Open the iOS Simulator Setup (Certificate menu -> Install Certificate on iOS -> Simulators) and click the button in Step 2. * Or try the steps in [Manually install the certificate by exporting it](#manually-install-the-certificate-by-exporting-the-certificate) below. ### 3. Some HTTP/HTTPS Requests are missing from Proxyman Alamofire or URLSession might use the cached response for your request. As a result, the actual request doesn't hit the server, so Proxyman cannot capture and display it. Solution: * Disable the cache mechanism on URLSession or Alamofire. * Use the [No Caching Tool](https://proxyman.com/docs/advanced-features/no-caching) (⌥⌘N) ## Manually Install the Certificate by exporting the certificate If you cannot install the certificate, you can do it **manually**: 1. Open Proxyman -> Certificate menu -> Export -> Root Certificate as DER -> Save to the Desktop folder 2. Open the Simulator, then **drag the certificate and drop it** on the Simulator screen 3. Open the Settings app (on the Simulator) -> General -> VPN & Device Management (Device Management on older iOS) -> Select the certificate -> Install 4. Settings app -> General -> About -> Certificate Trust Settings and verify that the Proxyman Certificate is installed and trusted. 5. Done ✅ ## Tutorial See detailed steps to [debug an application on iOS Simulator](https://proxyman.com/posts/2019-07-06-Debugging-on-iOS-Simulator-with-Proxyman) with Proxyman. ## Learn more * [How to inspect network traffic from iOS 15 Simulator with Proxyman](https://proxyman.com/posts/2022-06-04-How-to-inspect-network-traffic-from-iOS-simulator-with-Proxyman) * [Capture HTTPS requests from Vision Pro Simulator](https://proxyman.com/posts/2024-01-24-Capture-HTTPS-traffic-from-Vision-Pro-Simulator) * [Capture iOS Simulator HTTP/HTTPS traffic with Proxyman](https://proxyman.com/ios-simulator) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/tvos-and-watchos # tvOS & watchOS > Set up Apple TV and Apple Watch simulators or real devices with Proxyman to capture and inspect HTTP/HTTPS requests and responses from tvOS and watchOS. Proxyman can capture and intercept HTTP/HTTPS traffic from tvOS and watchOS. ## 1. watchOS ### Simulator Follow the [Proxyman iOS Simulator guide](https://proxyman.com/docs/debug-devices/ios-simulator). It works the same way for watchOS simulators. ### watchOS Physical Device Follow the [iOS device guide](https://proxyman.com/docs/debug-devices/ios-device) to set the HTTP Proxy and install the certificate on your host device. #### Tutorial: [https://proxyman.com/posts/2021-09-02-intercept-https-traffic-from-watch-os-simulator](https://proxyman.com/posts/2021-09-02-intercept-https-traffic-from-watch-os-simulator) ## 2. tvOS ### Simulator Capturing traffic from the tvOS simulator is easy. Follow the [iOS Simulator guide](https://proxyman.com/docs/debug-devices/ios-simulator). ### tvOS Devices Using Proxyman with a real Apple TV takes a few more steps. ✅ New Setup Guide (2024) * Follow this Medium article (from Raxit Majithiya): **Setup Proxyman in a physical AppleTV** [https://medium.com/@rax/setup-proxyman-in-a-physical-appletv-bf6df86d3a28](https://medium.com/@rax/setup-proxyman-in-a-physical-appletv-bf6df86d3a28) ⚠️ Old Setup Guide 1. Follow this tutorial: [https://www.willowtreeapps.com/craft/a-how-to-guide-for-apple-tv-setup-with-charles-proxy](https://www.willowtreeapps.com/craft/a-how-to-guide-for-apple-tv-setup-with-charles-proxy) 2. Use Proxyman instead of Charles Proxy. * Please note that the default Proxyman port is 9090 * Export the Proxyman Certificate from the Certificate menu -> Export * Make sure you install and trust the Proxyman Certificate before intercepting HTTPS traffic. > **Note:** If you can't set up Proxyman with watchOS or tvOS, please contact us at support@proxyman.com ## Learn more * [How to capture HTTP/HTTPS traffic from Apple Watch with watchOS 26](https://proxyman.com/posts/how-to-capture-https-from-apple-watch-watchOS-26) --- Source: https://proxyman.com/docs/debug-devices/android-device # Android Device & Emulator > Capture Android device and emulator HTTP/HTTPS traffic with desktop Proxyman, including proxy setup, certificates, automatic scripts, and Google Play images. This guide sends traffic from an Android device or emulator to Proxyman on your computer. It covers proxy configuration, certificate installation, and app certificate trust for HTTPS inspection. Choose the setup that matches your device: * **Physical Android device:** Follow the manual setup below. Your device must be able to reach the computer running Proxyman over the network. * **Android Emulator:** Start with the [automatic setup script](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator). * **Google Play emulator image:** Follow the [Google Play and Magisk guide](https://proxyman.com/docs/debug-devices/android-device/google-play-android-emulator-with-magisk). The standard automatic setup does not cover every image. To capture directly on a phone without a computer, use the [standalone Proxyman Android app](https://proxyman.com/android). For desktop capture, open the matching guide in Proxyman: * **Certificate** **Menu** -> **Install Certificate on Android -> Physical Devices…** * **Certificate Menu -> Install Certificate on Android -> Emulators…** > **Note:** Check out the [Mini Tutorial on how to set up Android devices & emulators](https://proxyman.com/docs/debug-devices/android-device/sample-android-project) > **Note:** For the **Android Emulator**, check out the [Automatic Script for Android Emulator](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator#1-whats-it) ## Video [Capture HTTPS from a native Android app (OkHttp) on the Android Emulator with API 36](https://www.youtube.com/watch?v=CWInB7gZj6g) [Video: Capture HTTP and HTTPS traffic on Android with the Proxyman for Android app](https://proxyman.com/videos/android) (44 seconds) ## 1. Android Setup Guide For manual setup, configure the device proxy first, then install the certificate and configure certificate trust in your development app. Installing the certificate alone does not make every Android app trust it. Follow all steps below: ![Proxyman Android Setup Guide with Wi-Fi proxy server and port, proxy.man/ssl link, and network security config XML](https://proxyman.com/docs/assets/proxyman-android-device-setup-guide.jpg) _Setup Guide for Android Devices_ Open the guide from **Certificate** menu -> **Install Certificate on Android** -> **Physical Devices…**, then follow these steps: 1. Install the **Root Proxyman Certificate** on your Mac: You can follow the [macOS Guide](https://proxyman.com/docs/debug-devices/macos). 2. Get your Android device or emulator -> Open the Settings app -> Wi-Fi -> Select the current Wi-Fi -> Configure the HTTP Proxy with the values in this table. | Name | Value | | -------------- | ------------------------------------------------- | | Server IP | Your Mac's current IP address | | Port | The current port of Proxyman: 9090 is the default | | Authentication | No | > **Note:** Some Samsung devices can't access the Internet after you set the HTTP Proxy. Please forget your current network and connect again. > > If **you're using any VPN app**, please make sure to close it, since some VPN apps conflict with HTTP/HTTPS Proxy configs. 3\. Open [http://proxy.man/ssl](http://proxy.man/ssl) or http://cert.proxyman.io in the web browser on your Android device to install the Proxyman Certificate. ### **Android 11, Android 12 or later:** * Visit http://proxy.man/ssl in the Google Chrome app to download the certificate. * From Android 11 or later, you have to install the certificate manually in the Settings app. * Settings app -> Security -> Encryption & Credentials -> Install a Certificate -> Select "CA Certificate" -> Select the Proxyman CA certificate in your storage. ### **Android 10 and below:** * As soon as you visit http://proxy.man/ssl, your Android device downloads and installs it automatically. Make sure you select the **VPN and App Section**. > **Note:** **On Android 12+**, if you see the warning "Can't install the Certificate: This file can't be used as a VPN & app user certificate", please select "CA Certificate" instead. > > Ref: [https://stackoverflow.com/a/70261393/3127477](https://stackoverflow.com/a/70261393/3127477) > **Note:** **http://proxy.man/ssl** is a local website, served by the HTTP server inside Proxyman. If you can't open it, forget the Wi-Fi network, reconnect, and make sure the Proxyman app is open. 4\. On Android 11 or later, verify the certificate: open Settings -> Security -> Encryption & Credentials -> Trusted Credentials -> User tab. Make sure you can see the **Proxyman CA** certificate, like in the screenshot below. ![Android Trusted credentials, User tab, listing the Proxyman CA certificate](https://proxyman.com/docs/assets/Screen_Shot_2020-09-29_at_9_00_46_PM%20(1).png) 5\. Open your app source code and add the following two `xml` files. * Add **res/xml/network\_security\_config.xml** ```markup title="network_security_config.xml" ``` * Add to **AndroidManifest.xml** ```markup title="manifest.xml" ... ``` > **Note:** Find more information at [Network Security Configuration ](https://developer.android.com/training/articles/security-config.html) > **Note:** Make sure that you **remove those configs in the Release build**. If not, your HTTP/HTTPS requests can be intercepted and leak your sensitive data in the Production build. 6\. If you use the Android Emulator, please restart the emulator 7\. Done ✅ ## **2. Troubleshooting** Please check out the [Android section of the device connection troubleshooting guide](https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy#android-devices-and-android-emulators). ## 3. Sample Android Project If you have trouble with the XML settings, check out this simple project that we've already configured: GitHub Link: [https://github.com/ProxymanApp/OKHTTP-Android-Sample](https://github.com/ProxymanApp/OKHTTP-Android-Sample) - [Sample Android Project](https://proxyman.com/docs/debug-devices/android-device/sample-android-project) ## 4. React Native Android app If you're using React Native for the Android app, please check out the [React Native Page](https://proxyman.com/docs/debug-devices/react-native). ## 5. Intercept Traffic from embedding WebView Some Android apps have an embedded WebView that needs extra steps to intercept HTTPS traffic. 1. Make sure you can see other HTTPS traffic from your Android app. It means that you've set up the certificate properly 2. Inject the following code into your WebView ```java if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) { WebView.setWebContentsDebuggingEnabled(true); } // The following two lines help with disabling asset caching webView.getSettings().setAppCacheEnabled(false); webView.getSettings().setCacheMode(WebSettings.LOAD_NO_CACHE); ``` 3\. Open a new Chrome tab on your computer and navigate to `chrome://inspect` 4\. When you open the WebView, it appears in your Chrome tab. Click `inspect` to start using the remote debugger. ## 6. SSL Proxying using Root Device > Credit for [Shirshak](https://github.com/shirshak55) If your Android version is below 7, you don't need this step. From Android 7, Google added extra security that blocks man-in-the-middle tools from reading app traffic by default. We don't bear any responsibility for problems caused by rooting phones. Please follow the guide at your own risk. > **Note:** Newer Proxyman versions store the certificate at `~/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem`. If the `~/.proxyman` folder does not exist on your Mac, use that folder instead, or export the certificate from the Certificate menu -> Export -> Root Certificate as PEM. 1. Root your phone with the `magisk` framework. 2. Install a root file browser so you can copy and paste files in a restricted system folder. 3. Type the following script in the command line ```bash $ cd ~/.proxyman // We copy certificate to another file name just so we may need it later $ cp proxyman-ca.pem temp.pem $ hash=$(openssl x509 -inform PEM -subject_hash_old -in temp.pem | head -1) $ mv temp.pem "$hash.0" ``` 4. In the `~/.proxyman` folder, you will see a file whose name starts with numbers and ends with `.0` 5. Copy that file to your Android device. 6. Use the root file browser to move that file to /system/etc/security/cacerts/ 7. Enjoy proxying. > **Note:** 1) On Android phones, set the gateway to a wrong IP, so you can be sure all your traffic goes through the Proxyman proxy only. > 2) You can use the macOS sharing feature to create a mobile hotspot. Then your Android phone can use the Proxyman proxy easily. This works better because the router sometimes blocks requests between the phone and the Mac. ## Additional Resources * Mitmproxy has a useful tutorial on how to install a system-trusted CA certificate on the Android Emulator. The same steps work with the Proxyman certificate: [https://docs.mitmproxy.org/stable/howto-install-system-trusted-ca-android/](https://docs.mitmproxy.org/stable/howto-install-system-trusted-ca-android/) ## Learn more * [How to install and trust self-signed certificates on Android 11](https://proxyman.com/posts/2020-09-29-Install-And-Trust-Self-Signed-Certificate-On-Android-11) * [How to capture HTTPS traffic from Android Emulators with API 35](https://proxyman.com/posts/capture_https_android_emulators) * [Proxyman is now available on Android](https://proxyman.com/posts/2026-05-25-Proxyman-is-now-available-on-Android) * [Capture Android device HTTP/HTTPS traffic with Proxyman](https://proxyman.com/android-device) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator # Automatic Script for Android Emulator > Use the Proxyman automatic script to set the HTTP proxy and install the Proxyman certificate on Android Emulators, so you can capture HTTPS in one click. ## 1. What's it? Manually overriding the HTTP Proxy, then installing and trusting the Proxyman Certificate on your Android Emulator, is complicated and error-prone. Proxyman provides a built-in script that does it for you in seconds. You can open it from **Certificate Menu -> Install Certificate on Android -> Emulators…** > **Tip:** From Proxyman 5.16.0 or later, Proxyman can install the Proxyman certificate into the system-level store. This makes it possible to decrypt all HTTPS traffic from Android Emulators. > **Note:** Proxyman now works with Google Play and non-Google Play Emulators. Override them in 1 click. See [google-play-android-emulator-with-magisk.md](https://proxyman.com/docs/debug-devices/android-device/google-play-android-emulator-with-magisk) ![Proxyman Android Emulator Setup Guide with Override All Emulators and the Install Proxyman VPN option checked](https://proxyman.com/docs/assets/Screenshot%202026-01-10%20at%2019.29.46.jpg) ## Video [Capture HTTPS from a native Android app (OkHttp) on the Android Emulator with API 36](https://www.youtube.com/watch?v=CWInB7gZj6g) ## 2. Benefit? **1 Click to:** * **✅ Auto** Override / Revert HTTP Proxy * **✅ Automatically** download, install, and trust the Proxyman Certificate in the system-level store. Decrypt all HTTPS from your Emulators. (Available on Proxyman 5.16.0 or later) * No need for **network\_security\_config.xml** * **✅** Less error-prone and done in a few clicks > **Tip:** Works with Android Emulators and Android Physical Devices via `adb` (Only for Proxyman v5.19.0+) ![Proxyman main window showing decrypted HTTPS requests from an OkHttp app running on the Android Emulator](https://proxyman.com/docs/assets/Capture_HTTPS_Android_Emulator_proxyman.jpg) _Capture and decrypt HTTPS from Android Emulators with Proxyman_ * Install Proxyman Certificate to the system-level Store. ### ✅ Flutter / React Native app From Proxyman macOS 6.4.0 or later, Proxyman can capture HTTPS traffic from Flutter apps without any code change. See the [flutter.md](https://proxyman.com/docs/debug-devices/flutter) documentation to learn more. ## 3. How to use it? 1. Make sure the `adb` command is installed. If not, please install it ```bash brew install android-platform-tools ``` 2. Open your Android app with Android Studio 3. Create a new Emulator in the Android Virtual Device Manager. **Make sure it's not a Google Play image. It must be a Google APIs image.** * ✅ NEW: Proxyman can now root Google Play Store Emulators. Please read [google-play-android-emulator-with-magisk.md](https://proxyman.com/docs/debug-devices/android-device/google-play-android-emulator-with-magisk) 4. Open Proxyman -> Certificate Menu -> Install Certificate on Android -> Emulators… -> Click the Override All Emulators button 5. Wait until the Terminal script completes 6. Relaunch your Android app from Android Studio 7. Proxyman will capture all HTTPS data ✅ > **Note:** If you close Proxyman, make sure to click the Revert All Changes button. Otherwise, your Android Emulator cannot access the Internet. ## 4. ⚠️ Proxyman 5.15.0 or earlier * Proxyman 5.15.0 or earlier can only install the Proxyman Certificate at the user level. * It means you have to complete the next step: * In your source code: * Add res/xml/network\_security\_config.xml ```xml ``` * Add to AndroidManifest.xml 
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:networkSecurityConfig="@xml/network_security_config">
        <activity
            ...
        </activity>
    </application>

</manifest>
## 5. Advanced: Run the script manually You can run the script manually in your Terminal app without granting the Automation permission in Privacy & Security. ### **Script path**: ```bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh ``` * For Proxyman 5.19.0 or later ```bash Usage: /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh -m [options] Modes: all Set proxy and install certificate proxy Set proxy only revertProxy Revert proxy settings only certificate Install certificate only Required Options based on Mode: -m, --mode : Operation mode (all, proxy, revertProxy, certificate) -i, --ip : IP address (required for all, proxy, certificate) -p, --port : Port number (required for all, proxy, certificate) -c, --cert : Path to Proxyman certificate (required for all, certificate) Optional Options: --include-physical : Include physical devices (default: only emulators) -h, --help : Show this help message ``` ### Prepare the certificate 1. Open the Proxyman app 2. Find the current IP in the main toolbar 3. Certificate menu -> Export -> Root Certificate as PEM -> Save to the Desktop folder ### 5.1 Override HTTP Proxy and Install the Certificate to system-level Store * Proxyman v5.19.0 or later (NEW) ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh --mode all --ip --port --cert ``` * Proxyman v5.18.0 or earlier ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh all ``` ### 5.2 Only Override HTTP Proxy * Proxyman v5.19.0 or later (NEW) ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh --mode proxy --ip --port ``` * Proxyman v5.18.0 or earlier ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh proxy ``` ### 5.3 Revert HTTP Proxy * Proxyman v5.19.0 or later (NEW) ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh --mode revertProxy ``` * Proxyman v5.18.0 or earlier ```bash bash /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Resources/install_certificate_android_emulator.sh revertProxy ``` ## 6. Left certificate expiry date 6.1 Problem: You get this error when intercepting HTTPS from an Android WebView ❗️ Android WebView rejects with ERR\_CERT\_VALIDITY\_TOO\_LONG You can change the leaf certificate's expiry in Proxyman Settings -> General -> **More** (next to the certificate) -> **Leaf Certificate Expiry**, then select a shorter expiry, such as 10 days. ![Proxyman Settings, General, with the certificate More menu open on Leaf Certificate Expiry set to 10 days](https://proxyman.com/docs/assets/Screenshot%202026-08-28%20at%2014.28.54.jpg) * Ref: [https://github.com/ProxymanApp/Proxyman/issues/2751](https://github.com/ProxymanApp/Proxyman/issues/2751) ## Learn more * [How to capture HTTPS traffic from Android Emulators with API 35](https://proxyman.com/posts/capture_https_android_emulators) * [How to capture HTTPS traffic from Flutter apps on Android Emulators](https://proxyman.com/posts/Capture-https-flutter-android-emulator) * [Capture Android Emulator HTTP/HTTPS traffic with Proxyman](https://proxyman.com/android-emulator) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/android-device/google-play-android-emulator-with-magisk # Google-Play Android Emulator with Magisk > Root Google Play Android Emulators with Magisk in one click from Proxyman, so Proxyman can install its certificate and capture HTTPS from your Android app. ## 1. What's it? From Proxyman macOS 6.14.0 or later, Proxyman can: * Override the HTTP proxy * Install the Proxyman Certificate into the system store on Google Play Android Emulator images ✅ (API 30+) ## 2. How to use it 1. Open Proxyman macOS 6.14.0 or later 2. Start your Android Emulators: Works with both non-Google Play and Google Play images 3. Certificate Menu -> Install Certificate on Android -> Emulators… 4. Check the "Root Google Play Emulators with Magisk" checkbox 5. Click Override All Emulators… 6. Done ✅ ![Proxyman Android Emulator Setup Guide with Root Google Play Emulators with Magisk checked and Override All Emulators](https://proxyman.com/docs/assets/Screenshot%202026-07-23%20at%2011.37.43.png) ## 3. How does it work? * Proxyman bundles Magisk.apk in the app and uses it to root your Emulators with 1 click. * You can audit it at /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Versions/A/Resources/Magisk ## Learn more * [How to capture HTTPS traffic from an Android API 36 Google Play Emulator with Proxyman and Magisk](https://proxyman.com/posts/2026-08-08-capture-https-android-api-36-google-play-emulator-magisk) --- Source: https://proxyman.com/docs/debug-devices/android-device/sample-android-project # Sample Android Project > Download a sample Kotlin Android project with OkHttp that shows how Proxyman captures and decrypts HTTPS traffic from an Android app or emulator. ## 1. What's it? A sample Kotlin Android project that shows how Proxyman can capture and decrypt HTTPS data from the OkHttp library. ![Proxyman main window showing HTTPS requests from the OkHttp sample app on the Android Emulator](https://proxyman.com/docs/assets/Capture_HTTPS_Android_Emulator_proxyman.jpg) _Capture and decrypt HTTPS traffic from Android_ ## 2. Download Download it from [https://github.com/ProxymanApp/OKHTTP-Android-Sample](https://github.com/ProxymanApp/OKHTTP-Android-Sample) ## Video [Capture HTTPS from a native Android app (OkHttp) on the Android Emulator with API 36](https://www.youtube.com/watch?v=CWInB7gZj6g) --- Source: https://proxyman.com/docs/debug-devices/firefox # Firefox > Capture HTTPS requests and responses from the Firefox browser with Proxyman, using 1-click Automatic Setup or by installing the Proxyman CA in Firefox. ## ✅ New Solution (Proxyman v5.19.0 or later - recommended) With Proxyman v5.19.0+, Proxyman can capture HTTPS requests and responses from Firefox with a 1-click setup. 1. Go to Setup Menu -> Automatic Setup 2. In the Web Browsers section -> Click the ⬇️ Arrow Button -> Select Firefox ![Proxyman Automatic Setup window with the Web Browsers menu to open Google Chrome or Firefox](https://proxyman.com/docs/assets/Screenshot%202025-04-28%20at%2009.53.27.jpg) _Capture HTTPS requests and responses from Firefox with Proxyman_ 3. A new Firefox instance will open 4. ✅ Done. Proxyman captures all traffic from this Firefox instance This setup makes Firefox or Google Chrome: * Automatically use Proxyman as the HTTP proxy * Automatically install and trust the Proxyman Certificate > **Tip:** Works with Google Chrome and Firefox ## ❌ Old Solution (Proxyman v5.18.0 or earlier) To intercept HTTPS traffic from Firefox, you need extra steps to install the Proxyman CA into Firefox's trust store. ### 1. Install Proxyman CA on macOS machine Before installing the Proxyman CA in Firefox, you have to install it properly on your Mac. Check out the macOS guide: - [macOS](https://proxyman.com/docs/debug-devices/macos) If you've done this step, you can skip to the next step. ### 2. Set Proxy on Firefox * Open Firefox Settings (CMD+,) * Search for Proxy and open the proxy settings * Select Use system proxy settings, or enter the Proxy IP and Port manually ### 3. Install Proxyman CA to Firefox 1. Open `http://proxy.man/ssl` in Firefox and download the certificate to your Downloads folder > **Note:** http://proxy.man/ssl is a local HTTP server, for better security. Please make sure the Proxyman app is open when you access this domain. 2\. Open Firefox Settings (CMD+,) and open the View Certificates window 3\. Open the Authorities tab and click the Import button ![Firefox Certificate Manager, Authorities tab, with the Import button](https://proxyman.com/docs/assets/Screen_Shot_2020-06-23_at_10_27_35.png) 4\. Select the Proxyman CA that you downloaded, and check all trust options. ![Firefox dialog to trust Proxyman CA to identify websites and email users](https://proxyman.com/docs/assets/Screen_Shot_2020-06-23_at_10_37_52.png) 5\. Reload the page that you need to intercept. Enjoy! ## Learn more * [How to capture HTTPS traffic from Firefox Browser](https://proxyman.com/posts/how-to-capture-https-traffic-firefox-browser) * [SSL debugging with Firefox](https://proxyman.com/posts/2020-01-22-Debug-With-Firefox) --- Source: https://proxyman.com/docs/debug-devices/java # Java VMs > Install the Proxyman Root CA certificate into all Java KeyStores on macOS with one script, so Proxyman can capture HTTPS traffic from Java and Kotlin apps. To intercept HTTPS traffic from Java apps, you need extra steps to install the Proxyman CA Certificate into the Java KeyStore. For example, to: * Intercept traffic from unit tests (written in Java or Kotlin) * Intercept traffic from a Java app or CLI ## 1. Benefit * Proxyman provides a script that automatically installs the Root Certificate into the Java KeyStore with 1 click ✅ * Supports `$JAVA_HOME` * Supports `SDKMAN` * Supports `/usr/libexec/java_home` ## 2. How to use? ### 1. Install Proxyman CA on your Mac Before installing the Proxyman CA on Java VMs, you have to install it properly on your Mac. Check out the macOS guide: - [macOS](https://proxyman.com/docs/debug-devices/macos) You can skip this step if you've already done it. ### 2. Install Proxyman CA to all Java Key Stores * Certificate Menu -> Install Certificate on Java VMs -> Run Script... ![Proxyman Certificate menu with Install Certificate on Java VMs open and Run Script highlighted](https://proxyman.com/docs/assets/proxyman-certificate-menu-java-run-script.jpg) _Run the Java certificate script_ * The script tries to find the KeyStore location from **JAVA\_HOME**, **SDKMAN**, or **$(/usr/libexec/java\_home)** and installs the CA Certificate if possible ![Terminal output of the Proxyman Java script installing the certificate into the Java cacerts KeyStore](https://proxyman.com/docs/assets/Screenshot%202025-02-15%20at%2014.20.51.jpg) _Proxyman installs the certificate into all Java trust stores it can find_ > **Note:** You can find the script at /Applications/Proxyman.app/Contents/Frameworks/ProxymanCore.framework/Versions/A/Resources/install-certificates-java.sh > **Note:** The script might ask for Automation permission, because Proxyman uses [AppleScript](https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html) to run it in the Terminal app with admin permission. ### Alternative solution * If you get the following error, check out the solution from @[**yauheniprakapenka**](https://github.com/yauheniprakapenka): [https://github.com/ProxymanApp/Proxyman/issues/569#issuecomment-723588490](https://github.com/ProxymanApp/Proxyman/issues/569#issuecomment-723588490) `sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target` --- Source: https://proxyman.com/docs/debug-devices/python # Python > Capture HTTP/HTTPS traffic from Python scripts and servers with Proxyman Automatic Setup. Works with requests, http.client, urllib3, httpx and aiohttp. ## 1. New Automatic Solution (v4.7.0 or later) ✅ Proxyman v4.7.0 or later can capture HTTP/HTTPS traffic from Python with 1 click. * 1-click solution: No need to set the HTTP Proxy config or trust the self-signed certificate manually. * Supports many Python libraries: requests, http.client, urllib3, httpx and aiohttp ### How to use: 1. Open Proxyman -> Setup Menu -> Automatic Setup 2. Click "Open New Terminal" 3. Accept the AppleScript permission prompt if needed 4. A new Terminal window opens -> Start your Python backend server or run your scripts there => Proxyman captures all traffic automatically. 5. Done ✅ ![Proxyman Automatic Setup window with the Open New Terminal button that captures Python libraries like aiohttp and httplib](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Capture Python traffic with Proxyman Automatic Setup_ Please check out the Automatic Setup page: - [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup) ## 2. Old Solution (Not recommended) ❌ ### 1. Script Approach 1. Use [this script from GitHub issue #1220](https://github.com/ProxymanApp/Proxyman/issues/1220#issuecomment-1249090359) to install or remove the certificate for Python automatically. 2. Save the script to your Desktop folder as `script.py` * Add Certificate: ```bash $ python3 script.py add ``` * Remove Certificate ``` $ python3 script.py remove ``` > **Note:** For macOS 12.2 or later, make sure you use `python3` > > Credit to [@novitae](https://github.com/novitae) ### 2. Manual Approach #### Install the Proxyman certificate in the Python environment By default, Python on macOS doesn't trust the Proxyman self-signed certificate. As a result, you might get an SSL error when you intercept HTTPS traffic. To intercept HTTPS traffic from your Python script, you have to explicitly **tell Python to use the Proxyman Root Certificate** at `~/.proxyman/proxyman-ca.pem` > **Note:** Newer Proxyman versions store the certificate at `~/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem`. If `~/.proxyman/proxyman-ca.pem` does not exist on your Mac, use that path in the commands below, or export the certificate from the Certificate menu -> Export -> Root Certificate as PEM. Please follow the guideline: 1. Install the Proxyman Certificate on your Mac (If you've done it, skip this step. If not, check out the [macOS guide](https://proxyman.com/docs/debug-devices/macos)). 2. Run the following commands in your Terminal app ```bash $ export SSL_CERT_FILE=~/.proxyman/proxyman-ca.pem $ export REQUESTS_CA_BUNDLE=~/.proxyman/proxyman-ca.pem $ echo "export REQUESTS_CA_BUNDLE=~/.proxyman/proxyman-ca.pem" >> ~/.bash_profile ; source ~/.bash_profile ``` 3\. Done. #### Revert the change If you don't use Proxyman, please revert the change by commenting out: ```bash # export REQUESTS_CA_BUNDLE=~/.proxyman/proxyman-ca.pem ``` in \~/.bash\_profile ## 3. Troubleshooting ### 3.1 Proxyman could not capture HTTP traffic from my Python code. **Solution**: Please use the [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup). ### Reference * [https://github.com/ProxymanApp/Proxyman/issues/948#issuecomment-890520435](https://github.com/ProxymanApp/Proxyman/issues/948#issuecomment-890520435) * [https://github.com/ProxymanApp/Proxyman/issues/1220](https://github.com/ProxymanApp/Proxyman/issues/1220) ## Learn more * [How to capture HTTPS traffic from Python requests or httpx library](https://proxyman.com/posts/2025-01-29-How-To-Capture-HTTPS-Traffic-From-Python-Requests-httpx) * [Capture HTTP/HTTPS traffic from Python with Proxyman](https://proxyman.com/python) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/ruby # Ruby > Capture HTTP/HTTPS traffic from Ruby scripts and servers with Proxyman Automatic Setup. Works with http, net/http, net/https, httparty and faraday. ## 1. New Automatic Solution (v4.7.0 or later) ✅ Proxyman v4.7.0 or later can capture HTTP/HTTPS traffic from Ruby with 1 click. * 1-click solution: No need to set the HTTP Proxy config or trust the self-signed certificate manually. * Supports many Ruby libraries: http, net/http, net/https, httparty, and faraday. ### How to use: 1. Open Proxyman -> Setup Menu -> Automatic Setup 2. Click "Open New Terminal" 3. Accept the AppleScript permission prompt if needed 4. A new Terminal window opens -> Start your Ruby backend server or run your scripts there => Proxyman captures all traffic automatically. 5. Done ✅ ![Proxyman Automatic Setup window with the Open New Terminal button that captures Ruby libraries like net/http](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Capture traffic from Ruby_ ## 2. Old Solution (Not Recommended) ### 1. Set HTTP Proxy to Ruby Net::HTTP automatically uses the proxy from the `http_proxy` environment variable if it is present. So you can use: ```bash ENV['http_proxy'] = 'http://127.0.0.1:9090' # your http://address:port here ``` and Net::HTTP will use it for all requests by default. Ref: [https://stackoverflow.com/questions/15792999/how-to-set-a-proxy-in-rubys-net-http](https://stackoverflow.com/questions/15792999/how-to-set-a-proxy-in-rubys-net-http) ### 2. Install Proxyman Certificate on Ruby By default, **Ruby** on macOS might not trust Proxyman's self-signed certificate. As a result, you might get an SSL error when you intercept HTTPS traffic. You can tell Ruby to use the Proxyman Certificate with the `SSL_CERT_FILE` env. ```bash $ env SSL_CERT_FILE=~/.proxyman/proxyman-ca.pem ruby my_script.rb ``` > **Note:** Newer Proxyman versions store the certificate at `~/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem`. If `~/.proxyman/proxyman-ca.pem` does not exist on your Mac, use that path instead, or export the certificate from the Certificate menu -> Export -> Root Certificate as PEM. ## Learn more * [Capture HTTP/HTTPS requests from Ruby (net::http, or http gem) scripts](https://proxyman.com/posts/2023-05-09-Capture-HTTP-HTTPS-Request-Response-From-Ruby-Net-HTTP-library) * [Capture HTTP/HTTPS traffic from Ruby with Proxyman](https://proxyman.com/ruby) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/nodejs # NodeJS > Capture HTTP/HTTPS traffic from NodeJS apps and scripts with Proxyman Automatic Setup. Works with axios, got, superagent, fetch and node-fetch. ## 1. New Automatic Solution (v4.7.0 or later) ✅ Proxyman v4.7.0 or later can capture HTTP/HTTPS traffic from NodeJS with 1 click. * 1-click solution: No need to set the HTTP Proxy config or trust the self-signed certificate manually. * Supports many NodeJS libraries: axios, got, superagent, fetch, and node-fetch ### How to use: 1. Open Proxyman -> Setup Menu -> Automatic Setup 2. Click "Open New Terminal" 3. Accept the AppleScript permission prompt if needed 4. A new Terminal window opens -> Start your NodeJS backend server or run your scripts there => Proxyman captures all traffic automatically. 5. For example: ``` $ npm start ``` Done ✅ ![Proxyman Automatic Setup window with the Open New Terminal button that captures NodeJS libraries like axios and fetch](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Capture NodeJS Traffic_ Please check out the Automatic Setup page: - [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup) ## 2. Old Solution (Not recommended) ❌ There are common problems when using NodeJS + Proxyman: ### 1. Proxyman could not capture http://localhost:3000 requests to my NodeJS Server If you're using NodeJS to serve a localhost website (e.g. http://localhost:3000), Proxyman might not work. For example: you use ExpressJS to serve an API server at http://localhost:3000 #### Solution: Please check out [I could not see any requests from my localhost server](https://proxyman.com/docs/troubleshooting/couldnt-see-any-request-from-localhost-server). ### 2. Proxyman could not capture HTTP requests, which are called from my NodeJS local server. * Requests from [fetch](https://www.npmjs.com/package/node-fetch) or [axios](https://github.com/axios/axios) don't show in the Proxyman app * I get an SSL error from HTTPS requests #### Solution By default, HTTP/HTTPS requests from your NodeJS libraries don't go through the HTTP proxy server, so Proxyman cannot capture the traffic. #### 2.1 node-fetch 1. Install the [global-agent](https://github.com/gajus/global-agent) package ```bash npm install global-agent ``` 2\. At the top of your NodeJS code, add the following code: ```javascript import { bootstrap } from 'global-agent'; bootstrap(); process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = '0'; ``` 3\. Add this env to your current shell. Make sure Proxyman is listening on port 9090 ``` export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:9090 ``` 4\. Done ✅ Run your NodeJS script again and the HTTP/HTTPS requests will appear in the Proxyman app. #### Sample code ```javascript import fetch from 'node-fetch'; // Setup global-agent import { bootstrap } from 'global-agent'; bootstrap(); process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = '0'; // fetch the data const response = await fetch('https://httpbin.org/get?id=123'); const data = await response.json(); // Done console.log(data); ``` #### 2.2 Axios According to the Axios documentation, you can set the HTTP\_PROXY and HTTPS\_PROXY environment variables. 1. Click the Proxyman icon in the menu bar -> Listen on \:\ 2. Click Copy Shell Command ![Proxyman menu bar menu with Listen on IP and port and the Copy Shell Command item](https://proxyman.com/docs/assets/Screenshot%202023-04-15%20at%2010.39.02.jpg) 3. Open the Terminal and paste the command. For example: export https\_proxy=http://192.168.1.103:9090 http\_proxy=http://192.168.1.103:9090 4. In the same Terminal -> Start your NodeJS server with axios. 5. Axios will send the traffic through Proxyman. 6. Done ✅ #### 2.3 I use a different NodeJS library If you're not using fetch or axios, the configuration might be different. Please check your library's documentation to see how to set the proxy and trust the Proxyman certificate. * Discussion at [https://github.com/ProxymanApp/Proxyman/issues/236](https://github.com/ProxymanApp/Proxyman/issues/236) ## Learn more * [Capture HTTP/HTTPS requests from axios (NodeJS)](https://proxyman.com/posts/2023-05-14-Capture-HTTP-HTTPS-Request-From-Axios-NodeJS) * [Debug OpenAI APIs in NodeJS with Proxyman](https://proxyman.com/posts/2025-03-30-Debug-OpenAPI-NodeJS) * [Capture HTTP/HTTPS traffic from NodeJS with Proxyman](https://proxyman.com/nodejs) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/rust # Rust > Configure the proxy and certificate handling for Rust reqwest requests so their HTTP/HTTPS traffic appears in Proxyman. ## 1. Problem Proxyman can't automatically capture HTTP/HTTPS traffic from `reqwest` in Rust because: * `reqwest` doesn't respect the system HTTP Proxy -> No traffic goes through Proxyman * `reqwest` doesn't trust the self-signed Proxyman Certificate -> You get an SSL error ## 2. Solution * Manually set the proxy to Proxyman at `http://localhost:9090` * Disable SSL verification ```rust use anyhow::Result; use reqwest::Url; #[tokio::main] async fn main() -> Result<()> { let proxy_url = Url::parse("http://localhost:9090")?; let client = reqwest::Client::builder() .danger_accept_invalid_certs(true) // trust self-signed certificate .proxy(reqwest::Proxy::https(proxy_url)?) // Proxy to Proxyman .build()?; let response = client.get("https://httpbin.org/get").send().await?; if response.status().is_success() { let body = response.text().await?; println!("Response Text: {}", body); } else { println!("Request failed with status: {}", response.status()); } Ok(()) } ``` > **Note:** For apps that ignore the system proxy, you can also try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension) (Beta, macOS 26 or later). It captures traffic without setting a proxy in each app. For HTTPS, your Rust client still has to trust the Proxyman certificate, or skip verification as shown above. --- Source: https://proxyman.com/docs/debug-devices/golang # Golang > Capture HTTP/HTTPS traffic from Go apps with Proxyman Automatic Setup. Works with net/http, fasthttp, resty, gorequest, req and grequests. ## 1. New Automatic Solution (macOS v5.17.0 or later) ✅ Proxyman macOS v5.17.0 or later can capture HTTP/HTTPS traffic from Golang with 1 click. * 1-click solution: No need to set the HTTP Proxy config or trust the self-signed certificate manually. * ✅ Supports many Go network libraries: net/http, fasthttp, resty, gorequest, req, grequests ### How to use: 1. Open Proxyman -> Setup Menu -> Automatic Setup 2. Select your favorite Terminal -> Click the "Open New Terminal" button 3. Accept the AppleScript permission prompt if needed ![Proxyman Automatic Setup window listing Golang libraries such as net/http and resty, with the Open New Terminal button](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Open a pre-configured Terminal to intercept HTTPS from Go_ 4. A new Terminal window opens -> Start your Golang backend server or run your scripts there => Proxyman captures all traffic automatically. 5. For example: ``` $ go run main.go ``` 6. Proxyman captures all HTTP/HTTPS traffic from Go, including net/http ![Terminal running go run main.go next to Proxyman showing captured requests from net/http, fasthttp and resty](https://proxyman.com/docs/assets/CleanShot%202025-03-18%20at%2009.56.44%402x.jpg) _Capture and intercept HTTPS traffic from Go net/http_ * Go Example Code: [https://github.com/ProxymanApp/golang-example](https://github.com/ProxymanApp/golang-example) ## 2. Old Solution (Not recommended ❌) * Proxyman can't capture any HTTP/HTTPS traffic from the Golang server. * The reason is that some network libraries (such as net/http) don't respect the system HTTP Proxy, so no traffic goes through the Proxyman app. ### 2.1 Solution #### net/http 1. Set the proxy to Proxyman. By default, it's at IP = localhost, port 9090 2. Tell the Transport to trust the Proxyman self-signed certificate. Otherwise, you get an SSL error because net/http rejects it. ```go package main import ( "crypto/tls" "fmt" "io/ioutil" "log" "net/http" "net/url" ) func main() { // Create a new HTTP client client := &http.Client{} // Configure the proxy proxyURL, err := url.Parse("http://localhost:9090") if err != nil { log.Fatal("Error parsing proxy URL:", err) } // Configure transport with proxy and TLS settings transport := &http.Transport{ Proxy: http.ProxyURL(proxyURL), TLSClientConfig: &tls.Config{ InsecureSkipVerify: true, // This allows self-signed certificates }, } // Set the transport for the client client.Transport = transport // Make a request resp, err := client.Get("https://example.com") if err != nil { log.Fatal("Error making request:", err) } defer resp.Body.Close() // Read the response body body, err := ioutil.ReadAll(resp.Body) if err != nil { log.Fatal("Error reading response:", err) } // Print the response fmt.Printf("Status: %s\n", resp.Status) fmt.Printf("Body: %s\n", string(body)) } ``` ## Learn more * [Capture HTTP/HTTPS traffic from Golang with Proxyman](https://proxyman.com/golang) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/react-native # React Native > Capture HTTPS traffic from React Native and Expo apps with Proxyman on iOS devices, iOS Simulators, Android devices and Android Emulators. ## Video [Capture HTTPS from a React Native Expo app on the iOS Simulator and Android Emulator](https://www.youtube.com/watch?v=4LkKXyIPulM) ## 1. React Native - iOS * If you're using React Native for the iOS app, follow the iOS guides. There is no difference from a native iOS app. * Works with Expo or the Metro bundler - [iOS Device](https://proxyman.com/docs/debug-devices/ios-device) - [iOS Simulator](https://proxyman.com/docs/debug-devices/ios-simulator) ## 2. React Native - Android Capturing HTTP/HTTPS traffic from React Native Android apps works like a native Android app. Please follow the Android setup guide: * [Android Physical Device](https://proxyman.com/docs/debug-devices/android-device) * [Android Emulator](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) > **Warning:** Make sure you've followed all steps in the guide, especially the **5th step**, where you add the **res/xml/network\_security\_config.xml** and **AndroidManifest.xml** > > Otherwise, Proxyman cannot decrypt the SSL connection. ## 3. Troubleshooting - Android ### 3.1 Metro bundle errors After you set the HTTP Proxy on your Android device to Proxyman, you might get the following error, because the Metro bundler cannot connect to its local server. ![React Native red screen on Android: Unable to load script, make sure you're running Metro](https://proxyman.com/docs/assets/Screenshot%202023-04-06%20at%2007.58.01.png) _Metro bundle errors_ To fix it: #### Android Emulator 1. Open Proxyman -> Certificate menu -> Install Certificate on Android -> Emulators… -> Click "Revert All Changes" 2. Open the Android Emulator -> Settings app -> Network -> Wi-Fi -> Open the proxy settings 3. Set the HTTP Proxy manually with the **Proxyman IP & Port**. If you don't know the IP & Port, open the Certificate menu -> Install Certificate on Android -> Physical Devices… and find the Server IP & Port in step 2. 4. Before saving, enter `localhost` in the bypass proxy list ✅ ![Android Wi-Fi proxy settings with the Proxyman IP and port and localhost in the bypass proxy list](https://user-images.githubusercontent.com/5878421/230129476-4bd5d1a0-c3c5-4c73-bb79-81f14a071e63.jpg) 5. Done 6. The `The Bridge Was shutdown` warning and the Metro bundle errors are gone ✅ #### Android Physical Device 1. Open the Android physical device -> Settings app -> Network -> Wi-Fi -> Open the proxy settings 2. Set the HTTP Proxy manually with the Proxyman IP & Port. If you don't know the IP & Port, open the Certificate menu -> Install Certificate on Android -> Physical Devices… and find the Server IP & Port in step 2. 3. Before saving, enter `your IP` in the bypass proxy list ✅ 4. Done Read more at: [https://github.com/ProxymanApp/Proxyman/issues/1407#issuecomment-1497235102](https://github.com/ProxymanApp/Proxyman/issues/1407#issuecomment-1497235102) ## Learn more * [How to capture HTTP/HTTPS traffic from Expo React Native iOS and Android apps](https://proxyman.com/posts/how-to-capture-https-from-React-native-app-2025-update) * [Capture HTTPS traffic from React Native apps with Proxyman](https://proxyman.com/posts/2023-09-25-Capture-HTTPs-Requests-From-React-Native-Apps) * [Capture HTTP/HTTPS traffic from React Native apps with Proxyman](https://proxyman.com/react-native) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/flutter # Flutter > Capture HTTPS traffic from Flutter apps with Proxyman on Android Emulators, Android devices, iOS Simulators and iPhones, with or without code changes. ## ✅ 1. New Solution > **Tip:** From Proxyman 6.4.0 or later, or Windows/Linux 3.7.0 or later ### Android Emulators Proxyman can capture HTTPS from your Flutter app on the Android Emulator in 1 click. Unlike the old solution, you don't need to change your Flutter code. 1. Start Proxyman -> Certificate Menu -> Install Certificate on Android -> Emulators… 2. Make sure you set up your Android Emulator first, and it must be a Google APIs image. See [automatic-script-for-android-emulator.md](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) to learn how to set up your Android Emulators 3. Check "Install Proxyman VPN on Android emulators" 4. Click "Override All Emulators" ![Proxyman Android Emulator Setup Guide with Install Proxyman VPN checked and the Override All Emulators button](https://proxyman.com/docs/assets/Screenshot%202026-01-10%20at%2019.29.46.jpg) _Capture HTTPS from a Flutter app on the Android Emulator with Proxyman_ 5. A new Terminal window opens and runs our bash script to override your Emulators. 6. When it's done, a new VPN app is installed on your Emulators 7. Tap the VPN button to start it -> Done ✅ 8. Open your Flutter app and make HTTPS requests. Proxyman will capture them ✅ ![Proxyman VPN app on the Android Emulator, connected and routing Flutter and React Native traffic to Proxyman](https://proxyman.com/docs/assets/Screenshot%202026-01-10%20at%2019.43.10.jpg) ## ⚠️ 2. Old Solution > **Warning:** The old solution works with Proxyman macOS 6.3.0 and earlier, Windows/Linux 3.6.0 and earlier ### 2.1 Problem [Flutter does not use the system-level proxy](https://github.com/flutter/flutter/issues/20376), so if you use Proxyman, you might not see any traffic from your Flutter project. The good news is that you can work around this issue by configuring Flutter’s HTTP client to use Proxyman as its proxy. In general, you have to configure the HTTP client to send all traffic to the Proxyman proxy server, which listens at IP = localhost, port = 9090. #### 1. Set up Flutter (Required for all platforms - iOS & Android) The steps are slightly different for each HTTP client. We cover some popular HTTP clients: * Dart’s [HttpClient](https://api.dartlang.org/stable/2.4.1/dart-io/HttpClient-class.html) class * The [http](https://pub.dev/packages/http) package * [Dio](https://pub.dev/packages/dio) If you're using an Android Emulator or an iOS Simulator, you can use `String proxy = 'localhost:9090'`. On Android physical devices, please use `String proxy = ':9090'`. You can find \ in Proxyman -> Certificate menu -> Install Certificate on iOS -> Physical Devices… Use the settings below for the network library that your Flutter app uses: #### Dart HTTPClient Class ```dart // Make sure to replace with // the external IP of your computer if you're using Android. // You can get the IP in the Android Setup Guide window String proxy = Platform.isAndroid ? ':9090' : 'localhost:9090'; // Create a new HttpClient instance. HttpClient httpClient = HttpClient(); // Hook into the findProxy callback to set // the client's proxy. httpClient.findProxy = (uri) { return "PROXY $proxy;"; }; // This is a workaround to allow Proxyman to receive // SSL payloads when your app is running on Android httpClient.badCertificateCallback = (cert, host, port) => true; ``` #### HTTP Package ```dart // Make sure to replace with // the external IP of your computer if you're using Android. // You can get the IP in the Android Setup Guide window String proxy = Platform.isAndroid ? ':9090' : 'localhost:9090'; // Create a new HttpClient instance. HttpClient httpClient = HttpClient(); // Hook into the findProxy callback to set // the client's proxy. httpClient.findProxy = (uri) { return "PROXY $proxy;"; }; // This is a workaround to allow Proxyman to receive // SSL payloads when your app is running on Android. httpClient.badCertificateCallback = (cert, host, port) => true; // Pass your newly instantiated HttpClient to http.IOClient. IOClient myClient = IOClient(httpClient); // Make your request as normal. final response = myClient.get('/my-url'); ``` #### Dio ≥ v5.0.0 (Recommended) ```dart // Make sure to replace with // the external IP of your computer if you're using Android. // You can get the IP in the Android Setup Guide window String proxy = Platform.isAndroid ? ':9090' : 'localhost:9090'; // Create a new Dio instance. Dio dio = Dio(); dio.httpClientAdapter = IOHttpClientAdapter( createHttpClient: () { final client = HttpClient(); client.findProxy = (uri) { return 'PROXY $proxy'; }; client.badCertificateCallback = (cert, host, port) => true; return client; }, validateCertificate: (cert, host, port) { return true; }, ); ``` #### Dio ＜ v5.0.0 (Deprecated APIs) ```dart // Make sure to replace with // the external IP of your computer if you're using Android. // You can get the IP in the Android Setup Guide window String proxy = Platform.isAndroid ? ':9090' : 'localhost:9090'; // Create a new Dio instance. Dio dio = Dio(); // Tap into the onHttpClientCreate callback // to configure the proxy just as we did earlier. (dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = (client) { // Hook into the findProxy callback to set the client's proxy. client.findProxy = (url) { return 'PROXY $proxy'; }; // This is a workaround to allow Proxyman to receive // SSL payloads when your app is running on Android. client.badCertificateCallback = (X509Certificate cert, String host, int port) => true; } ``` ### 2.2 Flutter with iOS Simulators 1. Start your iOS Simulator from Flutter 2. In Proxyman -> Certificate menu -> Install Certificate on iOS -> Simulators… 3. Follow all steps below ![Proxyman iOS Simulators Setup with three steps: certificate Installed & Trusted, Prepare Simulators, and Reboot](https://proxyman.com/docs/assets/proxyman-ios-simulators-setup.jpg) _Install & trust Proxyman certificate to your iOS Simulators_ 4. ✅ Done. Proxyman can capture your HTTPS traffic. ### 2.3 Flutter with iOS Devices * Follow the [iOS Device setup guide](https://proxyman.com/docs/debug-devices/ios-device) ### 2.4 Flutter with Android Emulator * Follow the [Automatic Script for Android Emulator guide](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) ### 2.5 Flutter with Android Devices * Follow the [Android Device setup guide](https://proxyman.com/docs/debug-devices/android-device) #### Credit & Reference Credit to James Dixon from [https://flutterigniter.com/debugging-network-requests/](https://flutterigniter.com/debugging-network-requests/) ## Learn more * [How to capture HTTPS traffic from Flutter apps on Android Emulators](https://proxyman.com/posts/Capture-https-flutter-android-emulator) * [How to capture HTTPS traffic from a Flutter iOS app](https://proxyman.com/posts/2024-11-11-capture-https-traffic-from-flutter-ios) * [Capture HTTP/HTTPS traffic from Flutter apps with Proxyman](https://proxyman.com/flutter) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/http-clients # HTTP Clients > Configure Postman, Insomnia, and Paw to send HTTP/HTTPS traffic through Proxyman and troubleshoot certificate errors. ## 1. Problems Proxyman might not capture requests, or you might get an SSL error, when you send HTTP/HTTPS requests from some HTTP clients, such as [Postman](https://www.postman.com/), [Insomnia Rest](https://insomnia.rest/), and [Paw](https://paw.cloud/). This page shows how to make them work with Proxyman. ## 2. Postman 1. Open Postman Settings 2. In the General tab -> Uncheck the "SSL certificate verification" checkbox 3. In the Proxy tab -> Check "Use the system proxy" and "Respect `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables". ![Postman Settings, Proxy tab, with Use the system proxy checked](https://proxyman.com/docs/assets/Postman_And_Proxyman.jpg) ## 3. Insomnia Rest 1. Open Insomnia Preferences -> General tab 2. Uncheck the "Validate certificates" checkbox 3. Check "Enable proxy" and enter `localhost:9090` in the HTTP Proxy and HTTPS Proxy text boxes. ![Insomnia Preferences with Validate certificates unchecked and the proxy set to localhost:9090](https://proxyman.com/docs/assets/Insomnia_And_Proxyman.jpg) ## 4. Paw By default, the Paw app uses the system proxy configuration, so Proxyman works out of the box. If you don't see any Paw traffic in Proxyman, please double-check: 1. Open Paw Preferences. 2. In the Network tab, make sure Proxy is set to System Proxy Configuration. ![Paw Preferences, Network tab, with Proxy set to System Proxy Configuration](https://proxyman.com/docs/assets/Paw_Proxyman.jpg) --- Source: https://proxyman.com/docs/debug-devices/docker # Docker > Capture HTTP/HTTPS traffic from Docker services and configure containers to route outgoing requests through Proxyman. ## 1. Capture traffic from your Docker Container By default, Proxyman can capture the requests that you send from your Mac to a service running in a Docker container. For example, here is a sample Docker container: 1. Set up a simple HTTP server with NodeJS + Express, then Dockerize it. You can find a guide at [https://nodejs.org/en/docs/guides/nodejs-docker-webapp/](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) 2. Make sure you expose your server on port 8080. 3. You can verify it by opening http://localhost:8080 in Safari. ## 2. Capture traffic inside Docker Containers Read the steps in [GitHub issue #419](https://github.com/ProxymanApp/Proxyman/issues/419#issuecomment-1059096490). ## 3. Alternative Solution: 1. Add docker-compose.proxyman.yml. Replace \ with your service ```yaml version: '2' services: php8.1-fpm-xdebug: environment: HTTP_PROXY: host.docker.internal:9090 HTTPS_PROXY: host.docker.internal:9090 http_proxy: host.docker.internal:9090 https_proxy: host.docker.internal:9090 ``` 2. Start Docker: `docker-compose -f docker-compose.yml -f docker-compose.proxyman.yml up -d` Ref: [https://github.com/ProxymanApp/Proxyman/issues/1712#issuecomment-1642279537](https://github.com/ProxymanApp/Proxyman/issues/1712#issuecomment-1642279537) --- Source: https://proxyman.com/docs/debug-devices/electronjs # ElectronJS > Capture HTTP/HTTPS traffic from ElectronJS apps with Proxyman in one click, even when the app ignores the system proxy. No source code changes needed. ## 1. Problem Many ElectronJS apps ignore the system HTTP proxy, so Proxyman can't capture HTTP/HTTPS traffic from them :x: ## 2. Solution From Proxyman macOS 6.7.0 or later: * Capture HTTP/HTTPS from ElectronJS apps * 1-click setup * No source code changes. It just works :white\_check\_mark: ## 3. How to use 1. Start the Proxyman app: Make sure you've already installed and trusted the Proxyman Certificate on your Mac. If not, follow the guide in Certificate Menu -> Install Certificate on this Mac -> Automatic Tab 2. Open the Setup Menu -> Automatic Setup 3. Click the "Select ElectronJS App…" button and select the app you'd like to capture (Make sure to quit your Electron app first) 4. Done :white\_check\_mark: ![Proxyman Automatic Setup window with the ElectronJS App section and the Select ElectronJS App button](https://proxyman.com/docs/assets/Screenshot%202026-03-02%20at%2016.11.10.jpg) ## Learn more * [Capture HTTP/HTTPS traffic from ElectronJS apps with Proxyman](https://proxyman.com/electron) (Proxyman website) --- Source: https://proxyman.com/docs/debug-devices/nextjs-fetch # NextJS (fetch) > Capture HTTPS requests from Next.js server-side fetch() and Server Components with the Proxyman pre-configured Terminal from Automatic Setup. ## 1. Problem * Proxyman can't capture any traffic from `use server` code in NextJS * It's because `fetch` in NextJS doesn't respect the system HTTP proxy. Therefore, no traffic goes through the Proxyman app. ## 2. Solution 1. Start the pre-configured Terminal: Setup menu -> Automatic Setup -> Click "Open New Terminal" 2. A new Terminal opens -> Start your NextJS server in this Terminal. For example: `npm run dev` 3. Use `no-cache` on `fetch` ```js export default async function MyPage() { const res = await fetch('https://httpbin.org/anything', { cache: 'no-cache' }) // no cache, or no request is sent to Proxyman return
My Page{res.text()}
} ``` 4. Reload your website 5. Done ✅ The Proxyman app captures your HTTP traffic ![Next.js dev server in the Proxyman pre-configured Terminal and the captured server-side fetch requests in Proxyman](https://proxyman.com/docs/assets/335782543-6e0c4eeb-435d-4589-b2dd-4087f3827f3a.jpg) _Capture NextJS fetch on Proxyman_ ## 3. Reference: * [https://github.com/ProxymanApp/Proxyman/issues/2038](https://github.com/ProxymanApp/Proxyman/issues/2038) ## Learn more * [Capture HTTP requests from the server side on NextJS](https://proxyman.com/posts/2024-06-10-Capture-HTTPS-From-NextJS-Server-Components) --- Source: https://proxyman.com/docs/debug-devices/demo-ios-and-android # Demo iOS & Android > Watch Proxyman demo videos that capture HTTPS from native and React Native apps on iOS Simulators and Android Emulators, with sample projects. ## 1. 📱 iOS Simulators ### 1.1 Native iOS app - iOS 26 Simulators + Xcode 26 [Capture HTTPS from a native iOS app on the iOS 26 Simulator with Xcode 26](https://www.youtube.com/watch?v=THzb2e9hoGo) ### 1.2 React Native with Expo with iOS 18 Simulator * Tutorial: [https://proxyman.com/posts/how-to-capture-https-from-React-native-app-2025-update](https://proxyman.com/posts/how-to-capture-https-from-React-native-app-2025-update) * Demo project: [https://github.com/ProxymanApp/Proxyman-React-Native-Sample-App](https://github.com/ProxymanApp/Proxyman-React-Native-Sample-App) [Capture HTTPS from a React Native Expo app on the iOS Simulator and Android Emulator](https://www.youtube.com/watch?v=4LkKXyIPulM) ## 2. 🤖 Android Emulators ### 2.1 Native Android app (Java or Kotlin) with Pixel 6 Pro (Google APIs version) + API 36 * Demo Project: [https://github.com/ProxymanApp/OKHTTP-Android-Sample](https://github.com/ProxymanApp/OKHTTP-Android-Sample) [Capture HTTPS from a native Android app (OkHttp) on the Android Emulator with API 36](https://www.youtube.com/watch?v=CWInB7gZj6g) ### 2.2 React Native with Expo | Pixel 9 Pro Google APIs with API 36 * Tutorial: [https://proxyman.com/posts/how-to-capture-https-from-React-native-app-2025-update](https://proxyman.com/posts/how-to-capture-https-from-React-native-app-2025-update) * Demo project: [https://github.com/ProxymanApp/Proxyman-React-Native-Sample-App](https://github.com/ProxymanApp/Proxyman-React-Native-Sample-App) [Capture HTTPS from a React Native Expo app on the iOS Simulator and Android Emulator](https://www.youtube.com/watch?v=4LkKXyIPulM) --- Source: https://proxyman.com/docs/automatic-setup/automatic-setup # Automatic Setup > Use Proxyman Automatic Setup to open a pre-configured Terminal and capture HTTP/HTTPS traffic from NodeJS, Python, Ruby, Golang and cURL in one click. ## 1. Problems Proxyman **could not capture** HTTP/HTTPS traffic from the following setup: * **NodeJS**: Axios, got, superagent, fetch, and node-fetch * **Python**: http, https, aiohttp, requests * **Ruby**: http, net/http, net/https, faraday, httparty, and fastlane * Golang: net/http, fasthttp, resty, gorequest, req, grequests * ElectronJS * cURL It's a known issue: NodeJS, Python, Ruby, and cURL run from the Terminal app don't use the system HTTP proxy. So there is no traffic in Proxyman. You have to read the technical documentation of each library and manually configure: * The HTTP Proxy * Trust for a self-signed certificate \=> Time-consuming and error-prone ❌ ## 2. Solution: Automatic Setup ### Benefit: * ✅ **1-click to automatically set up HTTP Proxy & Certificate** on a variety of dev environments * Capture HTTP(s) traffic from NodeJS, Python, Ruby, Golang, Terminal or Web Browser, etc. * Safe. It works in your current session and doesn't affect your OS ### How to use: 1. Open Proxyman -> **Setup** menu -> **Automatic Setup…** 2. Click **Open New Terminal…**. You can pick Apple Terminal, iTerm2, or Ghostty from the menu next to it. 3. Accept the AppleScript permission prompt if needed 4. The new Terminal window opens -> Start your backend server or run your scripts => Proxyman automatically captures all traffic. 5. Done ✅ ![Proxyman Automatic Setup window with Apple Terminal and Open New Terminal, plus Web Browsers and ElectronJS App sections](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Start the pre-configured Terminal app_ ![Terminal window showing the Proxyman Automatic Setup scripts message, ready to start a backend server](https://proxyman.com/docs/assets/CleanShot%202023-04-26%20at%2015.53.00%402x.jpg) _New Terminal app is launched_ ### Notes: * Automatic Setup can open Apple Terminal, iTerm2, or Ghostty. To use another Terminal app (for example Hyper), select **My own Terminal…** in the same menu or use the [Manual Setup](https://proxyman.com/docs/automatic-setup/manual-setup). * It's safe because it only runs in your current session. It doesn't change your system configuration. #### ElectronJS 1. Open a new Terminal from Automatic Setup 2. Use this command line: ``` open ~/Applications/your_electron_app.app ``` You can also click **Select ElectronJS App…** in the Automatic Setup window. See [ElectronJS](https://proxyman.com/docs/debug-devices/electronjs). ### Support Libraries: Proxyman (with Automatic Setup) works out of the box with the following network libraries. * NodeJS: [axios](https://www.npmjs.com/package/axios), [fetch](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch) (v18+), [node-fetch](https://www.npmjs.com/package/node-fetch), [got](https://www.npmjs.com/package/got), [https](https://nodejs.org/api/https.html), and [superagent](https://www.npmjs.com/package/superagent) * Ruby: [http](https://ruby-doc.org/stdlib-3.0.2/libdoc/net/http/rdoc/Net/HTTP.html), [net/http](https://ruby-doc.org/stdlib-2.7.0/libdoc/net/http/rdoc/Net/HTTP.html), [net/https](https://ruby-doc.org/stdlib-2.7.0/libdoc/net/http/rdoc/Net/HTTP.html), [httparty](https://github.com/jnunemaker/httparty), [faraday](https://github.com/lostisland/faraday), and fastlane * Python: [requests](https://pypi.org/project/requests/), [aiohttp](https://docs.aiohttp.org/en/stable/), http.client, urllib3 and httpx * Golang: net/http, fasthttp, resty, gorequest, req, grequests * ElectronJS app * cURL without --proxy flag > **Tip:** It's completely **SAFE** since the change only affects your current Terminal session. It doesn't change your **bash\_profile** or **zshrc** file. ## 3. Advanced: How does it work? When you click **Open New Terminal…**, Proxyman does the following: 1. Uses AppleScript to start the Terminal app. 2. Runs this command line in the new Terminal window: ```bash set -a && source "$HOME/.proxyman/proxyman_env_automatic_setup.sh" && set +a ``` 3. proxyman\_env\_automatic\_setup.sh is a bash script that sets the environment variables Proxyman needs. For example: * HTTP\_PROXY & HTTPS\_PROXY env * PATH * RUBYLIB * PYTHONPATH * NODE\_OPTIONS * GLOBAL\_AGENT\_HTTP\_PROXY **NodeJS**: 1. Proxyman prepends a new Node directory to the $PATH env. 2. Proxyman monkey-patches Node with the [global-agent](https://www.npmjs.com/package/global-agent) package, which adds HTTP proxy support to axios and fetch. **Ruby**: 1. Overrides $RUBYLIB to point to the Proxyman app 2. Patches common libraries, such as http, net/http and net/https -> Sets the HTTP proxy and trusts the Proxyman self-signed certificate. **Python**: 1. Overrides $PYTHONPATH to point to the Proxyman app 2. Patches common libraries, such as aiohttp, httplib, http.client -> Sets the HTTP proxy and trusts the Proxyman self-signed certificate. **Go**: 1. Overrides HTTP\_PROXY & HTTPS\_PROXY env 2. Overrides some Go env to trust the self-signed certificate ## 4. Troubleshooting See the [Troubleshooting](https://proxyman.com/docs/automatic-setup/troubleshooting) page. ## Learn more * [Capture HTTP/HTTPS Request from axios (NodeJS)](https://proxyman.com/posts/2023-05-14-Capture-HTTP-HTTPS-Request-From-Axios-NodeJS) * [Capture HTTP/HTTPS Request from Ruby (net::http, or http gem) scripts](https://proxyman.com/posts/2023-05-09-Capture-HTTP-HTTPS-Request-Response-From-Ruby-Net-HTTP-library) * [How to capture HTTPS traffic from Python requests or httpx library](https://proxyman.com/posts/2025-01-29-How-To-Capture-HTTPS-Traffic-From-Python-Requests-httpx) --- Source: https://proxyman.com/docs/automatic-setup/manual-setup # Manual Setup > Use Proxyman Manual Setup to capture HTTPS traffic from NodeJS, Python, Ruby and cURL in your own Terminal app, such as iTerm2, with Bash, Zsh or Fish. ## 1. Problems Proxyman **could not capture** HTTP/HTTPS traffic from the following setup: * **NodeJS**: Axios, got, superagent, fetch, and node-fetch * Python: http, https, aiohttp, requests * Ruby: http, net/http, net/https, faraday, httparty and fastlane * cURL It's a known issue: NodeJS, Python, Ruby, and cURL run from the Terminal app don't use the system HTTP proxy. So there is no traffic in Proxyman. You have to read the technical documentation of each library and manually configure: * The HTTP Proxy * Trust for a self-signed certificate \=> Time-consuming and error-prone ❌ ## 2. Solution: Manual Setup ### Benefit: * ✅ Run on your favorite Terminal app: iTerm2 with Bash, Zsh, and Fish Shell * Capture HTTP(s) traffic from NodeJS, Python, Ruby, Terminal or Web Browser, etc. * Safe. It works in your current session and doesn't affect your OS ### How to use: 1. Open Proxyman -> **Setup** menu -> **Manual Setup…** 2. Open your favorite Terminal app, such as iTerm2 3. Click **Copy to Clipboard**, then paste the command into your Terminal and run it 4. Done ✅ 5. Start your backend server or run a script => Proxyman automatically captures all HTTP/HTTPS traffic ![Proxyman Manual Setup window with the source command for your Terminal and the Copy to Clipboard button](https://proxyman.com/docs/assets/proxyman-manual-setup-window.jpg) _Copy the command to your Terminal_ ### Support Libraries: Proxyman (with Manual Setup) works out of the box with the following network libraries. * NodeJS: [axios](https://www.npmjs.com/package/axios), [fetch](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch) (v18+), [node-fetch](https://www.npmjs.com/package/node-fetch), [got](https://www.npmjs.com/package/got), [https](https://nodejs.org/api/https.html), and [superagent](https://www.npmjs.com/package/superagent) * Ruby: [http](https://ruby-doc.org/stdlib-3.0.2/libdoc/net/http/rdoc/Net/HTTP.html), [net/http](https://ruby-doc.org/stdlib-2.7.0/libdoc/net/http/rdoc/Net/HTTP.html), [net/https](https://ruby-doc.org/stdlib-2.7.0/libdoc/net/http/rdoc/Net/HTTP.html), [httparty](https://github.com/jnunemaker/httparty), [faraday](https://github.com/lostisland/faraday), and fastlane * Python: [requests](https://pypi.org/project/requests/), [aiohttp](https://docs.aiohttp.org/en/stable/), http.client, urllib3 and httpx * cURL without --proxy flag ## 3. Advanced: How does it work? See [Automatic Setup: How does it work?](https://proxyman.com/docs/automatic-setup/automatic-setup#3-advanced-how-does-it-work) ## 4. Troubleshooting See the [Troubleshooting](https://proxyman.com/docs/automatic-setup/troubleshooting) page. --- Source: https://proxyman.com/docs/automatic-setup/troubleshooting # Troubleshooting > Fix common Proxyman Automatic Setup and Manual Setup problems: missing traffic from NodeJS, Python or Ruby, SSL errors, and localhost requests. ## 1. Automatic Setup does not capture any HTTP Traffic from my new networking library Proxyman supports the following libraries: * **NodeJS**: Axios, got, superagent, fetch, and node-fetch * **Python**: http, https, aiohttp, requests * **Ruby**: http, net/http, net/https, faraday, and httparty \-> If you're using a new library and Proxyman Automatic Setup doesn't capture your HTTP/HTTPS traffic, please [create a new ticket on GitHub](https://github.com/ProxymanApp/Proxyman/issues) to request support for your library. > **Note:** If your library running on your Mac ignores proxy settings, try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension). It captures supported HTTP/HTTPS traffic without relying on Automatic Setup's proxy configuration. Certificate trust is still required for HTTPS. > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## 2. I get SSL Errors from my NodeJS, Ruby, Python script \-> Make sure you've installed and trusted the certificate on macOS. Open the **Certificate** menu -> **Install Certificate on this Mac…**. \-> If the error still happens, there may be a bug in the Automatic Setup feature. Please [create a new ticket on GitHub](https://github.com/ProxymanApp/Proxyman/issues) and let us know. ## 3. Proxyman could not record any traffic from my local server, e.g http://localhost:3000 By default, traffic from http://localhost:3000 doesn't go through the system proxy. Therefore, Proxyman can't capture it. Follow [I could not see any requests from my localhost server](https://proxyman.com/docs/troubleshooting/couldnt-see-any-request-from-localhost-server) to fix it. --- Source: https://proxyman.com/docs/atlantis/atlantis-for-ios # Atlantis for iOS > Use the Atlantis iOS framework to send HTTP/HTTPS and WebSocket traffic from your app to Proxyman for macOS, without proxy or certificate setup. ## 1. What's it? Atlantis is a lightweight iOS framework by Proxyman for intercepting HTTP/HTTPS and WS/WSS traffic from your iOS app. You don't need to set up a proxy or a certificate. ![Atlantis by Proxyman logo](https://proxyman.com/docs/assets/cover.png) * **GitHub**: [https://github.com/ProxymanApp/atlantis](https://github.com/ProxymanApp/atlantis) ## 2. Benefit? * Automatically intercept all **HTTP/HTTPS** Traffic with ease. * Automatically intercept **WebSocket** from iOS devices. * Support iOS Physical Devices and Simulators * **No need** to configure an HTTP Proxy, or install and trust any Certificate * Review traffic logs in the [Proxyman](https://proxyman.com/) macOS app. * Categorize the log by app and devices. > **Note:** **Atlantis** is only for **Network Inspectors**. If you want to use Debugging Tools like Map Local, Breakpoint, Map Remote, Scripting, Network Throttling, and Reverse Proxy, please use a normal Proxy. ![Proxyman macOS app showing Atlantis traffic grouped by iOS device and app in the sidebar](https://proxyman.com/docs/assets/proxyman_atlantis.png) ## 3. How to install Please check out the latest install guide on the GitHub page: [https://github.com/ProxymanApp/atlantis](https://github.com/ProxymanApp/atlantis) --- Source: https://proxyman.com/docs/basic-features/proxy-setting-tool # Proxyman Proxy Helper Tool > Install the Proxyman Proxy Helper Tool to change and restore the macOS system proxy faster, and to let guest or non-admin users capture traffic. > **Note:** Proxyman also offers [Network Extension](https://proxyman.com/docs/advanced-features/network-extension) to capture HTTP/HTTPS traffic from Mac apps that ignore proxy settings. The Helper Tool manages the system proxy; Network Extension captures supported traffic without per-app proxy setup. > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## What is the Proxy Helper Tool? By default, Proxyman changes your HTTP/HTTPS proxy settings with the [networksetup](https://www.unix.com/man-page/osx/8/networksetup/) command-line tool. However, **networksetup** is slow and can delay starting or quitting the app. Proxyman offers a faster solution: the **Proxyman Proxy Helper Tool**. It is a macOS [Privileged Helper Tool](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/AccessControl.html#//apple\_ref/doc/uid/TP40002589-SW2) that changes the network proxy settings with **high performance**. > **Note:** You can see the difference by starting the app with and without the Proxy Helper Tool. On first launch, Proxyman asks you to install the Proxy Helper Tool. You can skip it and install it later in **Settings** → **Advanced**. ![Proxyman Settings Advanced tab showing Proxy Helper Tool installed, version 1.7.0, with an Uninstall button](https://proxyman.com/docs/assets/proxyman-settings-advanced-proxy-helper-tool.jpg) _Proxy Helper Tool in Settings, Advanced_ > **Note:** After the installation, you can find the Helper Tool at `/Library/PrivilegedHelperTools/com.proxyman.NSProxy.HelperTool` > > When Proxyman ships a new version of the Proxy Helper Tool, you need to install it again. ### Grant permission on macOS 13 Ventura or later On macOS 13 Ventura or later, you must allow the Helper Tool in System Settings before it can work. To grant the permission: 1. Open **System Settings** → **General** → **Login Items** (**Login Items & Extensions** on macOS 15 or later). 2. Find Proxyman and switch it ON ✅ If the permission is missing, **Settings** → **Advanced** in Proxyman shows an **Open Login Items…** button that takes you there. ![macOS System Settings Login Items with the Proxyman switch turned on](https://proxyman.com/docs/assets/Screenshot%202022-11-20%20at%2021.10.43.png) _Grant permission to Proxyman Helper Tool_ ### Guest or non-admin users If you're a guest or non-admin user, the `networksetup` command fails and cannot change the HTTP/HTTPS proxy settings until you install the Proxy Helper Tool. The Proxy Helper Tool has the privileges to change the proxy settings for all kinds of users. If you're a guest or non-admin user, we highly recommend installing the Proxy Helper Tool for a smoother experience. ### Uninstall the Proxy Helper Tool You can uninstall the Proxy Helper Tool in **Settings** → **Advanced** → **Uninstall**, or delete it directly at `/Library/PrivilegedHelperTools/com.proxyman.NSProxy.HelperTool` ## Install the Proxy Helper Tool by command line From Proxyman for macOS 4.12.0 or later, you can install the Helper Tool without the GUI: ``` sudo /Applications/Proxyman.app/Contents/MacOS/proxyman --install-privileged-components ``` ## Changelog ### Version 1.6.0 (Proxyman 5.11.0 or later) * Fixed: Proxyman can't restore the PAC URL when the app is closed ### **Version 1.5.0** * Fixed a security vulnerability where Proxyman v1.5.0 or older (2019) could connect to the Helper Tool (v1.4.0) and override the system proxy without user consent. The fix adds constraints to verify the incoming connection: the caller must be notarized by Apple, signed with the Proxyman LLC certificate, and have Library Validation and the Force Hard flag enabled. (CVE-2023-45732) 📣 Credit to **Scott Leitch** from NCC Group. ### **Version 1.4.0** * Comply with new macOS 13 Ventura Requirements for Helper Tool * Show App Icon & App Name on the Login-Items > **Note:** On macOS Ventura or later, helper tools, launch daemons, and launch agents are listed under **Allow in the Background**, even though Proxyman only runs in the foreground. > > There is an ongoing [discussion on Twitter](https://twitter.com/siracusa/status/1583914093437935616?s=46\&t=C1XB91IkDFkG697Ab8T9Dg) asking Apple to fix this in macOS. After you install version 1.4.0, the Login Items entry might not update because macOS caches it. ![macOS Login Items entry showing an old cached name and blank icon instead of Proxyman](https://proxyman.com/docs/assets/Screen%20Shot%202022-10-25%20at%2010.00.04.png) _Login Items shows an old cached entry_ To fix it: 1. Open the Terminal app and run: `sfltool resetbtm` 2. Restart your Mac 3. Done ### **Version 1.3.0** * Remember and restore to your previous Proxy Setting. ### Version 1.2.0 * Gracefully revert the HTTP Proxy Config if Proxyman crashes. ## Troubleshooting If you see this error when installing the Helper Tool: The operation couldn’t be completed. (CFErrorDomainLaunchd error 9.) Follow the steps in this article: [Fix CFErrorDomainLaunchd error 9 (Tencent Cloud)](https://cloud.tencent.com/developer/article/1816504) Related GitHub issue: [ProxymanApp/Proxyman#1113](https://github.com/ProxymanApp/Proxyman/issues/1113) --- Source: https://proxyman.com/docs/basic-features/request-response-viewer # Request / Response Previewer > Inspect requests and responses in Proxyman with Header, Cookies, Query, Body, Raw and JSON Tree View tabs, and arrange the panels to fit your work. After installing the [Certificate](https://proxyman.com/docs/debug-devices/macos) and enabling [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) on domains or apps, your network traffic shows up immediately in the Proxyman window. The window has three main areas: * The Source List on the left panel * The Flow List on the middle panel * The Flow Content on the right panel ![Proxyman main window with the Source List, the request list, and a POST request JSON body with a 201 Created response](https://proxyman.com/docs/assets/proxyman-main-window.jpg) _Proxyman main window_ ## Body Content Previewer Depending on the content of the request or response, Proxyman automatically shows it in separate tabs: * **Header**: All headers (key-value table) * **Cookies**: The **Cookie** header of the request * **Set-Cookie**: The Set-Cookie header of the response * **Auth**: The **Authorization** header * **Body**: The body of the message. Proxyman automatically formats and beautifies the body based on the **Content-Type**, such as JSON, PNG, GIF, Raw Data, ... * **Query**: All query parameters of the request * **Raw**: The raw HTTP message * [Protobuf](https://proxyman.com/docs/advanced-features/protobuf) Message * MessagePack * [Multipart/form-data](https://proxyman.com/docs/basic-features/multipart-form-data-previewer) ## Custom Previewer Tab You can choose which previewer tabs you would like to see: * Custom tabs stay on the Request/Response panel * Proxyman tries to decode and beautify the content in the selected format - [Custom Previewer Tab](https://proxyman.com/docs/basic-features/custom-previewer-tab) ![Proxyman Custom Body Previewer Tabs window with format checkboxes for the Request and Response panels](https://proxyman.com/docs/assets/proxyman-custom-previewer-tab-window.jpg) _Choose your previewer tabs_ ## Layout mode There are two ways to arrange the Request / Response panels: [Vertical or Horizontal layout](https://proxyman.com/docs/basic-features/horizontal-vertical-layout). ## Customize Workspace Use the layout buttons in the top-right corner of the app to arrange the content the way you like: 1. Collapse/Expand the Source List panel 2. Open the Request/Response panel in a new window 3. Show the Request/Response panel in Horizontal layout 4. Show the Request/Response panel in Vertical layout ![Proxyman toolbar with the layout buttons on the right for Source List, Detachable Window, Horizontal and Vertical](https://proxyman.com/docs/assets/proxyman-toolbar-layout-buttons.jpg) _Layout buttons in the toolbar_ ## Shortcuts All sections support **Copy (⌘C)** and multiple selection. Read more in our [Proxyman keyboard shortcuts](https://proxyman.com/posts/2019-08-20-Useful-shortcuts-that-boost-your-productivity) blog post. ## **Body Previewer** The Body previewer automatically beautifies the content and offers handy extra features: * **Tree View**: Show the JSON in Tree View mode * **Hex**: Show the body in Hex format * **Export only body**: Export the body content to a file. Useful for raw or binary data * **Open With**: Open the body content in your favorite editor. **Sublime Text** is mine 😍 ## JSON Tree View mode Proxyman has a native JSON Tree View mode for JSON bodies. It lets you: * Search JSON by [JSON Path](https://proxyman.com/docs/basic-features/jsonpaths) * Copy a JSON node, like in Google Chrome DevTools ## Learn more * [Preview multipart/form-data bodies from HTTP requests and responses](https://proxyman.com/posts/2021-06-24-preview-multipart-formdata) --- Source: https://proxyman.com/docs/basic-features/connection-log # Connection Log > Use the Proxyman Connection Log to inspect DNS lookups, TCP connections, TLS handshakes, certificates, and HTTP headers for each request. ## 1. What's it? Connection Log shows how Proxyman connects to a server and sends your request. It uses a text format similar to `curl -v`, with colors to help you find key details. * Follow the connection from the DNS lookup to the HTTP response. * See the steps Proxyman captured while handling the request. * Inspect the connection between Proxyman and the upstream server. * Read the log in the Request panel, next to Summary. ![Connection Log in the Request panel showing DNS results, a TLS handshake, certificate details, and request headers](https://proxyman.com/docs/assets/connection-log.png) _Connection Log showing the steps of an HTTPS request_ ## 2. Benefits * Find where a connection failed: DNS lookup, TCP connection, or TLS handshake. * Check which host and IP address Proxyman connected to. * See the TLS version and HTTP protocol the server accepted. * Check the server certificate's name, issuer, and expiry date. * See whether a request reused an existing connection. * Save the captured details to review later or share with your team. ## 3. How to use it? 1. Open Proxyman for macOS and capture a request. 2. Select the request in the main list. 3. In the Request panel, click **Connection Log**, immediately after **Summary**. The tab is enabled by default for new users and existing users after upgrading. The log updates while the selected connection is active. To show or hide it: * Click the **+** button in the Request tab bar to open [Custom Previewer Tab](https://proxyman.com/docs/basic-features/custom-previewer-tab). * Under Request, check or uncheck **Connection Log**. * Proxyman remembers your choice after restarting. For HTTPS request and response content, set up the Proxyman certificate and enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain. Without SSL Proxying, encrypted content stays hidden and fewer connection details are available. ## 4. What does it show? The log lists the details available for the selected request. ### DNS and TCP connection * The host name and port. * IPv4 and IPv6 addresses returned by the DNS lookup. * Each connection attempt and any failed attempts. * The IP address and port of the connected server. * An upstream proxy, when one is used. * Whether the connection was reused, left open, or closed. ### TLS handshake and certificate * Protocols offered through ALPN, such as `h2` or `http/1.1`. ALPN lets Proxyman and the server choose an application protocol. * Handshake steps, such as `Client hello`, `Server hello`, `Certificate`, and `Finished`. * The negotiated TLS version and cipher suite on the `SSL connection using` line. * The protocol accepted by the server. * Certificate subject, issuer, DNS/IP names, and validity dates. * Certificate and hostname verification results, plus TLS alerts or failures. ### HTTP request and response * The request method, path, HTTP version, and headers. * The response status and headers. * A text response body preview, when available. * Messages explaining when a body was decoded, modified, or shortened for display. Use the **Timing** tab when you want to compare DNS, TCP, and TLS durations. ## 5. How to read it? * `*` marks a connection event or diagnostic message. * `>` marks request headers sent to the server. * `<` marks response headers received from the server. * `OUT` and `IN` show the direction of a TLS message from Proxyman's point of view. Colors help you scan the log: * Cyan: host names and IP addresses. * Purple: TLS versions and ALPN protocols. * Blue: handshake steps. HTTP header names use the same style as the Raw tab. * Green: successful handshake steps and verification results. * Amber: warnings, such as disabled certificate verification. * Red: failures, such as a rejected certificate or a connection timeout. `Certificate verification disabled` means Proxyman did not verify the server certificate for that connection. It does not mean the certificate is invalid. Likewise, `Hostname verification: not performed` means that check was skipped. A reused connection may not show a new DNS lookup or TLS handshake for every request. ## 6. Save and reopen the log * [Export the flow](https://proxyman.com/docs/basic-features/import-export) as a Proxyman Log `.proxymanlogv2`, or [save the session](https://proxyman.com/docs/advanced-features/save-session). * Reopen the file and select **Connection Log** to view the saved connection details. * Proxyman saves the recorded events and builds the displayed log when you open the tab. * Certificate details are saved as text fields. Full certificates, certificate chains, and private keys are not saved with the connection details. * Older captures without connection details can still open. The log shows the saved HTTP data and explains that connection details were not recorded. ## Learn more * [HTTP/2 is finally here in Proxyman v26.0.0](https://proxyman.com/posts/2026-09-19-http2-is-finally-here) --- Source: https://proxyman.com/docs/basic-features/ssl-proxying # SSL Proxying > Set up SSL Proxying in Proxyman to decrypt and inspect HTTPS traffic from selected apps and domains, using host names or wildcard rules. SSL Proxying tells Proxyman which apps and domains to decrypt, so you can read their HTTPS requests and responses in plain text. For HTTP/2 traffic on macOS, also enable **Use HTTP/2** in Settings. See the [HTTP/2 guide](https://proxyman.com/docs/basic-features/http2) for setup and protocol checks. Certificate trust and SSL Proxying are still required to inspect HTTPS content. ## Video [Video: Capture HTTP and HTTPS traffic with Proxyman](https://proxyman.com/videos/capture-http-https-traffic) (25 seconds) ## 1. SSL Proxying List The SSL Proxying List is a list of domains or apps whose SSL connections Proxyman should decrypt. It lets you inspect HTTPS requests and responses in plain text. ### Include List and Exclude List You can define rules for: * **Include List**: Intercept the traffic from apps/domains in the Include List * **Exclude List**: Ignore all traffic from apps/domains in the Exclude List ![Proxyman SSL Proxying List window, Include List tab with jsonplaceholder.typicode.com, httpbin.proxyman.app and Safari](https://proxyman.com/docs/assets/proxyman-ssl-proxying-list.jpg) _SSL Proxying Include List_ > **Note:** Press ⌘⌥P to quickly open the SSL Proxying List. ### Apps / Domains / Wildcards Proxyman supports several formats to define a rule: * **By app**: Intercept all traffic from this app * **By domain**: Intercept all traffic from this domain * **Wildcard**: Intercept traffic from every domain that matches the wildcard For example: | Wildcard | Description | | --------------------------- | ---------------------------------------------------------- | | \* | Decrypt ALL HTTPS traffic | | \*.domain.com, \*.apple.com | e.g. v1.domain.com, data.domain.com, health.apple.com, ... | | v?.domain.com | e.g. v1.domain.com, v2.domain.com, ... | > **Note:** You must set up the Proxyman Certificate before intercepting any HTTPS requests. Follow the [macOS setup guide](https://proxyman.com/docs/debug-devices/macos) to install and trust the certificate. ### How to enable SSL Proxying on a particular domain or app * Right-click the app or domain in the left panel → **Enable SSL Proxying**. If it is already on, the menu shows **Disable SSL Proxying** instead. ![Proxyman sidebar right-click menu on a domain with the SSL Proxying toggle below Open as New Tab and Open as Split View](https://proxyman.com/docs/assets/proxyman-open-as-new-tab-menu.jpg) _Sidebar menu for a domain_ * Right-click the request in the main table → **Enable SSL Proxying** * Select the request and enable SSL Proxying in the Response panel. ![Proxyman Response panel for an encrypted HTTPS response with Enable only this domain and Enable all domains buttons](https://proxyman.com/docs/assets/proxyman-enable-ssl-proxying-response-panel.jpg) _Enable the entire app or a single domain_ ## Learn more * [Can we bypass SSL Pinning?](https://proxyman.com/posts/2019-11-15-Can-we-bypass-ssl-pinning) --- Source: https://proxyman.com/docs/basic-features/http2 # HTTP/2 > Turn on HTTP/2 in Proxyman for macOS to capture HTTP/2 traffic and inspect requests, responses, trailers, and the negotiated protocol. ## 1. What's it? HTTP/2 lets several requests share one connection at the same time. Proxyman captures each request and response as a separate exchange, so you can inspect them with the usual previewers and debugging tools. > **Note:** HTTP/2 is available in the regular Proxyman macOS release from v26.0.0. It is off by default. A separate beta app is no longer needed. ## 2. Benefits * Inspect HTTP/2 requests and responses from apps and browsers that use Proxyman. * Follow concurrent requests on a shared connection. * Read headers, bodies, and trailer headers sent after a body. * Check the HTTP version used by a captured request. * Inspect the upstream protocol in [Connection Log](https://proxyman.com/docs/basic-features/connection-log), when recorded. HTTP/2 uses header compression and connection reuse to reduce overhead. Results depend on the app, server, and network. Enabling it does not make every request faster. ## 3. How to enable it? 1. Open Proxyman v26.0.0 or later on your Mac. 2. Go to **Proxyman → Settings → General**. 3. In the **Proxy** section, turn on **Use HTTP/2**. 4. For HTTPS content, install and trust the Proxyman certificate on the client device. 5. Enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the app or domain. 6. Send a fresh request or reload the page. ![Proxyman Settings General tab with Use HTTP/2 checked below the port number and recording options](https://proxyman.com/docs/assets/proxyman-settings-use-http2.jpg) _Turn on Use HTTP/2_ > **Warning:** Changing this setting closes existing connections. Send fresh requests afterward. Active WebSocket and Server-Sent Events connections may also need to reconnect. For certificate setup, see the [macOS guide](https://proxyman.com/docs/debug-devices/macos). A remote device must trust the certificate and send its traffic through Proxyman on your Mac. See the [iOS](https://proxyman.com/docs/debug-devices/ios-device) or [Android](https://proxyman.com/docs/debug-devices/android-device) setup guide. To turn HTTP/2 off, uncheck **Use HTTP/2** in the same Settings section. For scripts, use `proxyman-cli http-version status` or `proxyman-cli http-version set prefer_http2`. See the [HTTP version command-line guide](https://proxyman.com/docs/command-line#15-http-version) for syntax and JSON output. ## 4. What does it capture? Select a request in the main list to inspect the available details: * Request method, URL, query parameters, cookies, and headers. * Request and response bodies, such as JSON, form data, text, or binary content. * Response status and headers. * Request and response trailers, when present. * Timing and HTTP version information. * Recorded connection details, including upstream protocol negotiation. Trailers are headers sent after the body. For gRPC traffic, check `grpc-status` and `grpc-message` in the headers or trailers. HTTP 200 alone does not prove the RPC succeeded. Binary payloads may need further decoding. ## 5. How to check the protocol? The setting allows HTTP/2 with HTTP/1.1 fallback. It does not guarantee that every request uses HTTP/2. There are two connections: * The client connection, from your app or browser to Proxyman. * The upstream connection, from Proxyman to the server. These connections can use different HTTP versions. Check the request's HTTP version for the client connection. Open **Connection Log** in the Request panel to inspect the upstream protocol, when recorded. * `h2` means HTTP/2. * `http/1.1` means HTTP/1.1. * An offered protocol is not proof that the server selected it. Check the accepted protocol. * Older saved captures may lack upstream protocol details. Missing data does not mean HTTP/1.1. ## 6. Connection info in Connection Log * Select a request, then open **Connection Log** in the Request panel, next to **Summary**. * Read a log similar to `curl -v`, with DNS results, connection attempts, TLS and certificate details, and HTTP headers. * Check `ALPN: server accepted h2` to confirm the upstream connection uses HTTP/2. Reused connections are marked with `Re-using existing connection`. * `*` marks connection events, `>` marks the request, and `<` marks the response. Example excerpt with sample values: ```text * Host api.example.com:443 was resolved. * IPv4: 192.0.2.10 * Connected to api.example.com (192.0.2.10) port 443 * ALPN: Proxyman offers h2,http/1.1 * SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256 * ALPN: server accepted h2 * using HTTP/2 > GET /profile HTTP/2 < HTTP/2 200 OK * Connection #0 to host api.example.com left intact ``` If the tab is hidden, enable **Connection Log** under Request in [Custom Previewer Tab](https://proxyman.com/docs/basic-features/custom-previewer-tab). See the [Connection Log guide](https://proxyman.com/docs/basic-features/connection-log) for all fields. ## 7. Troubleshooting If a request still uses HTTP/1.1: * Check **Use HTTP/2**, then send a fresh request. * Confirm the client supports and negotiates HTTP/2. * Check whether the upstream server supports HTTP/2. Fallback may be expected. * Inspect both connections before deciding which side used HTTP/1.1. If HTTPS content is missing: * Check that the client sends its traffic through Proxyman. * Check certificate trust and the domain's SSL Proxying rule. * If the client rejects the certificate, see [SSL errors](https://proxyman.com/docs/troubleshooting/get-ssl-error-from-https-request-and-response). ## 8. Related guides * [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) * [Connection Log](https://proxyman.com/docs/basic-features/connection-log) * [Split View](https://proxyman.com/docs/basic-features/split-view) * [Tab View](https://proxyman.com/docs/basic-features/multiple-tabs) * [Upstream ALPN and HTTP/2 Scripting settings](https://proxyman.com/docs/scripting/snippet-code#upstream-alpn-and-http2-settings) * [HTTP/2 release blog](https://proxyman.com/posts/2026-09-19-http2-is-finally-here) --- Source: https://proxyman.com/docs/basic-features/bypass-proxy-list # Bypass Proxy List > Use the Proxyman Bypass Proxy List to choose domains that skip the proxy, with wildcard matching, so you can hide noise and avoid SSL pinning errors. ## 1. Bypass Proxy List The Bypass Proxy List helps developers to: * ✅ Define a list of domains that **never** go through the Proxyman proxy server * Ignore noisy traffic * Avoid SSL errors caused by SSL Pinning when the traffic goes through Proxyman ## 2. How to use it? 1. Open the Bypass Proxy List from **Tools** → **Proxy Settings** → **Bypass Proxy Settings…**. You can also open **Tools** → **SSL Proxying List…** and click **Bypass Proxy Setting…** 2. Enter your list of domains, separated by commas. Simple wildcards (`*` and `?`) are supported. ![Proxyman Bypass Proxy Settings sheet with a comma-separated domain list and a note that * and ? wildcards work](https://proxyman.com/docs/assets/proxyman-bypass-proxy-settings.jpg) _Define the Bypass Proxy List_ ## 3. How does it work? 1. As soon as Proxyman launches, it replaces your system Bypass Proxy List with the Proxyman list. You can find the system setting in **System Settings** → **Wi-Fi** → **Details…** (next to your network) → **Proxies** → **Bypass proxy settings for these hosts & domains**. 2. When you quit the app, Proxyman restores your original setting. ## Learn more * [Can we bypass SSL Pinning?](https://proxyman.com/posts/2019-11-15-Can-we-bypass-ssl-pinning) --- Source: https://proxyman.com/docs/basic-features/import-export # Import / Export > Import and export traffic in Proxyman: open Proxyman Log, HAR and Charles files, and export requests as Proxyman Log, HAR, CSV or Postman Collection. ## 1. Import Proxyman can open traffic log files from Proxyman, Charles Proxy, and other apps that export HAR files. * **Proxyman Log**: Built-in Proxyman Log that contains all Requests and Responses information. * **Proxyman Session**: Entire working session files that are exported from the Proxyman app. * **HAR 1.2** ([HTTP Archive](https://en.wikipedia.org/wiki/HAR\_\(file\_format\))): Useful for moving HTTP requests and responses between apps to inspect later. Charles, Google Chrome, Safari, Firefox, and other network analyzer apps are fully supported. * **Charles Proxy Log**: Charles log exported from the Charles Proxy app. The file extension is **chls**. * **Charles Proxy Log for iOS** (Proxyman 2.30.0+): The file extension is **chlsj**. If you would like to save an entire working session, please read the Save Session page. - [Save Session](https://proxyman.com/docs/advanced-features/save-session) - [Charles Proxy Converter](https://proxyman.com/docs/advanced-features/charles-proxy-converter) ## 2. Export You can export: * A list of selected requests or responses. * All traffic from a specific client, domain node, or remote device. * An entire working session. * The Body or Raw content of a request or response. Export formats: * **Proxyman Log** or **Proxyman Session** * **HAR** (HTTP Archive) * **CSV File**: Export selected requests as a CSV file (Proxyman 2.29.0+) * **Postman Collection 2** It's useful to export a buggy request that you can investigate later or send to your QA team. ## 3. Import & Export by Command Line Proxyman offers a command line tool that lets you import and export from a bash script. - [Command-line](https://proxyman.com/docs/command-line) ## 4. How to use ### 4.1 Import files to Proxyman * **Drag and drop** files to the Proxyman window * **File** → **Open…** (⌘O) → Select a file The imported file is added to the Pinned section in the sidebar, where you can inspect all traffic. ### 4.2 Export to files There are many ways to export the selected requests to files: * Select requests in the main table → Right-click → **Export** * Right-click the app or domain in the sidebar → **Export** * Select requests → **Flow** → **Export** in the menu bar ![Proxyman request context menu with the Export submenu: Share Online, Proxyman Log, HAR, CSV, Postman, Gist and OpenAPI](https://proxyman.com/docs/assets/proxyman-export-requests-menu.jpg) _Export the selected requests_ ## Learn more * [How to open the HAR file from Google Chrome](https://proxyman.com/posts/2026-06-16-How-to-open-the-HAR-file-from-Google-Chrome) * [Migrate from Charles to Proxyman](https://proxyman.com/posts/2020-07-03-Migrate_From_Charles_To_Proxyman) --- Source: https://proxyman.com/docs/basic-features/content-filter # Content Filter > Use the Proxyman Content Filter to find requests fast by type, status code, URL, header, body and more, with contains, wildcard and regex matching. Proxyman offers the Primary and Secondary Filters to quickly find the requests or responses you're looking for. > **Note:** **⌘F**: Open the Filter Bar > > **ESC**: Close the Filter Bar ![Proxyman filter bar with HTTPS, JSON, Form, 2xx and 4xx selected, so only matching requests show in the list](https://proxyman.com/docs/assets/proxyman-content-filter-bar.jpg) _Select several filters at once_ ![Proxyman Secondary Filter key menu with URL, Host, Query String, Header, Body, Method, Status Code, Comment and Color](https://proxyman.com/docs/assets/proxyman-filter-key-menu.jpg) _Choose what to filter_ ![Proxyman filter matching menu with Contains, Start With, Equal, number comparisons, Match Wildcard and Match Regex](https://proxyman.com/docs/assets/proxyman-filter-matching-menu.jpg) _Choose how to match_ ## Primary Filter | Filter | Description | | --------- | --------------------------------------------------------------- | | All | All Requests and Responses | | HTTP | Only HTTP | | HTTPS | Only HTTPS | | WebSocket | Only WebSocket and Secure WebSocket | | JSON | Content-Type is application/json or JSON contents | | Form | Only Form Body in Request / Response | | XML | Only XML | | JS | Only JavaScript content | | CSS | Only CSS content | | GraphQL | GraphQL requests (the URL contains `/graphql`) | | Document | Document content: HTML, ... | | Media | Image, audio and video content: PNG, JPG, GIF, ... | | Other | Other content that doesn't match any of the above | | h1 | Only HTTP/1.x requests | | h2 | Only [HTTP/2](https://proxyman.com/docs/basic-features/http2) requests | ## Status Filters | Filter | Description | | ------ | ---------------------------- | | 1xx | Status codes from 100 to 199 | | 2xx | Status codes from 200 to 299 | | 3xx | Status codes from 300 to 399 | | 4xx | Status codes from 400 to 499 | | 5xx | Status codes 500 and above | > **Note:** Hold the ⌘ key and click to select multiple types. ## Secondary Filter ### Content * URL * Host * Query String * Request Header * Response Header * Request Body * Response Body * Method * Status Code * Duration (ms) * Request Body Size (KB) * Response Body Size (KB) * GraphQL * Client * IP Address * Comment * Color ### Matching * Contains * Not Contains * Start With * End With * Equal * Not Equal * `<` (less than, for numbers) * `>=` (greater than or equal, for numbers) * Match Wildcard * Not Match Wildcard * Match Regex * Not Match Regex ## Header, Query, Auth, Form Filter From Proxyman 2.34.0+, you can quickly filter the Header, Query, Auth, and Form content of the selected request and response. 1. Click the view (e.g. the Header tab of the Request) 2. Press ⌘F or right-click → **Show Filter** to open the filter ## Learn more * [Use Multiple Filters to find HTTP requests faster](https://proxyman.com/posts/2021-04-08-Use_Multiple_Filters) --- Source: https://proxyman.com/docs/basic-features/multiple-tabs # Tab View > Use Proxyman Tab View on macOS to organize traffic in Safari-style tabs, each with its own source, filters and selected request. ## 1. What's it? Tab View lets you keep several traffic views open in one Proxyman window. The new tab bar in v26.0.0 follows familiar Safari-style controls, with tabs you can switch, reorder, and close. Each tab keeps its own selected source, filters, and request selection while you move between tabs. Live tabs share the same incoming capture. > **Note:** Tab View requires Proxyman PRO. The new Safari-style tab bar is available in Proxyman v26.0.0 or later for macOS. ![Proxyman tab bar with Apps, httpbin.proxyman.app and jsonplaceholder.typicode.com tabs, the last one selected](https://proxyman.com/docs/assets/proxyman-tab-view-tab-bar.jpg) _Tab View with three tabs_ ## 2. Benefits * Keep different apps, domains, or endpoints in separate views. * Switch between investigations without rebuilding your filters. * Drag tabs into an order that matches your workflow. * Open [Split View](https://proxyman.com/docs/basic-features/split-view) inside a tab when you need two panes at once. ## 3. How to open a tab? * Press **⌘T** to open a new tab. * Click the **+** button in the tab bar. * Right-click an app or domain in the sidebar and choose **Open as New Tab**. Select the source and filters you want in the new tab. Other tabs keep their own view settings. ![Proxyman sidebar right-click menu on a domain with Open as New Tab highlighted above Open as Split View](https://proxyman.com/docs/assets/proxyman-open-as-new-tab-menu.jpg) _Open a domain as a new tab_ ## 4. Switch and organize tabs * Click a tab to select it. * Drag a tab left or right to reorder it. * Use the tab list menu to find a tab when there are too many to fit. * Use the keyboard shortcuts below to move between tabs. The sidebar follows the active view. When a tab has Split View open, click the pane you want to work with before choosing an app or domain. ## 5. Close tabs Click a tab's close button, or right-click a tab and choose: * **Close Tab** to close that tab. * **Close Other Tabs** to keep that tab and close the others. * **Close Tabs to the Right** to close the tabs after it. Press **⌘W** to close the current tab when the main traffic window is active. Closing the last tab closes that window. ![Proxyman tab right-click menu with New Tab, Close Tab, Close Other Tabs and Close Tabs to the Right](https://proxyman.com/docs/assets/proxyman-tab-close-menu.jpg) _Close tabs from the tab menu_ ## 6. Keyboard shortcuts | Shortcut | Action | | --- | --- | | ⌘T | Open a new tab | | ⌘W | Close the current tab in the main traffic window | | ⌘⇧1–9 | Select the first through ninth tab | | ⌘⇧] | Select the next tab | | ⌘⇧[ | Select the previous tab | | Control-Tab | Select the next tab | | Control-Shift-Tab | Select the previous tab | > **Note:** Use **⌘⇧1–9** for numbered tab selection. Proxyman uses **⌘1–6** for request color shortcuts, so numbered tab selection differs from Safari. ## 7. Related guides * [Split View](https://proxyman.com/docs/basic-features/split-view) * [Content Filter](https://proxyman.com/docs/basic-features/content-filter) * [Horizontal/Vertical/Window Layout](https://proxyman.com/docs/basic-features/horizontal-vertical-layout) * [License](https://proxyman.com/docs/license) ## Learn more * [HTTP/2 is finally here in Proxyman v26.0.0](https://proxyman.com/posts/2026-09-19-http2-is-finally-here) (introduces Tab View and Split View) --- Source: https://proxyman.com/docs/basic-features/split-view # Split View > Use Proxyman Split View on macOS to compare two traffic panes side by side, each with its own filters, selected request and inspector. ## 1. What's it? Split View shows two traffic panes side by side in the same tab. Each pane has its own request list, filters, selected request, and inspector. Both panes share the same capture. You can inspect two endpoints or compare requests from different apps without switching back and forth. > **Note:** Split View is available in Proxyman v26.0.0 or later for macOS and requires Proxyman PRO. ![Proxyman Split View with httpbin requests on the left and jsonplaceholder requests on the right, each with an inspector](https://proxyman.com/docs/assets/proxyman-split-view.jpg) _Two panes in Split View_ ## 2. Benefits * Keep two apps, domains, or endpoints visible at the same time. * Use different filters in each pane. * Select a request in each pane and compare their headers, bodies, or status codes. * Watch new requests arrive while keeping another request open for reference. * Combine Split View with [Tab View](https://proxyman.com/docs/basic-features/multiple-tabs) to organize your work. ## 3. How to open it? Use the toolbar: 1. Open the tab you want to split. 2. Click **Show Split View** in the main toolbar. 3. Click inside either pane to make it active. Or open an app or domain directly: 1. Right-click the app or domain in the sidebar. 2. Select **Open as Split View**. 3. Proxyman opens it in the second pane. If the second pane is already open, Proxyman uses that pane. ![Proxyman sidebar right-click menu on a domain with Open as Split View highlighted below Open as New Tab](https://proxyman.com/docs/assets/proxyman-open-as-split-view-menu.jpg) _Open a domain in Split View_ Proxyman supports two panes per tab. Opening another source as Split View changes the second pane instead of adding a third one. ## 4. Work with each pane * Click a pane before selecting a source in the shared sidebar or using a toolbar action. * Apply filters to the active pane. The other pane keeps its own filters. * Select different requests in the two lists. Each inspector shows its pane's selected request. * Drag the divider to adjust the width of the panes. Newly opened split panes put their inspectors below the request lists. You can change the inspector position with the existing [layout controls](https://proxyman.com/docs/basic-features/horizontal-vertical-layout). To compare two endpoints: 1. Filter the first pane to the profile endpoint. 2. Filter the second pane to the activity endpoint. 3. Reproduce the action in your app. 4. Select a request in each pane and compare the results. For highlighted differences between two requests or responses, use the [Diff tool](https://proxyman.com/docs/advanced-features/diff). ## 5. How to close it? Click **Hide Split View** in the toolbar to return to the first pane. Closing the second pane does not delete the captured traffic. Each tab has its own layout. You can keep Split View open in one tab and use a single pane in another. ## 6. Related guides * [Tab View](https://proxyman.com/docs/basic-features/multiple-tabs) * [Content Filter](https://proxyman.com/docs/basic-features/content-filter) * [Multiple Filters](https://proxyman.com/docs/advanced-features/multiple-filters) * [Horizontal/Vertical/Window Layout](https://proxyman.com/docs/basic-features/horizontal-vertical-layout) ## Learn more * [HTTP/2 is finally here in Proxyman v26.0.0](https://proxyman.com/posts/2026-09-19-http2-is-finally-here) (introduces Split View and Tab View) --- Source: https://proxyman.com/docs/basic-features/horizontal-vertical-layout # Horizontal/Vertical/Window Layout > Change the Proxyman workspace layout: dock the Request and Response panels to the bottom or right, open them in a separate window, or hide the sidebar. To compare two traffic lists in the same tab, use [Split View](https://proxyman.com/docs/basic-features/split-view). To organize traffic across tabs, use [Tab View](https://proxyman.com/docs/basic-features/multiple-tabs). The controls below change the Request and Response inspector layout. You can change the layout of the Request and Response panels to make more room for the content. * **Detachable Window**: Move the Request and Response panels to a separate window * **Vertical**: Show the Request and Response panels on the right of the request list * **Horizontal**: Show the Request and Response panels below the request list ![Proxyman toolbar with the layout buttons on the right for Source List, Detachable Window, Horizontal and Vertical](https://proxyman.com/docs/assets/proxyman-toolbar-layout-buttons.jpg) _Layout buttons in the toolbar_ ![Proxyman in Vertical layout with the Request and Response panels docked to the right of the request list](https://proxyman.com/docs/assets/proxyman-vertical-layout.jpg) _Vertical layout_ You can also use these shortcuts or the **View** menu: | Shortcut | View menu | Description | | -------- | ---------------------------- | ----------------- | | ⌃⌘↑ | Detach Content Windows | Detachable Window | | ⌃⌘[ | Toggle Source List Panel | Toggle Left Panel | | ⌃⌘\\ | Toggle Dock to Right Window | Vertical Mode | | ⌃⌘] | Toggle Dock to Bottom Window | Horizontal Mode | --- Source: https://proxyman.com/docs/basic-features/copy-as # Copy as > Copy requests and responses in Proxyman as a URL, cURL command, Markdown table, CSV or raw text, or copy just the headers, cookies or body. Proxyman offers various Copy functions from the right-click context menu: * **Copy URL** (⌘C): Copy the URL of the selected flow. * **Copy cURL** (⇧⌘C): Generate a cURL command, which includes headers, cookies, query, and body. * **Copy Cell Value**: Copy the string value of the right-clicked cell. * **Copy as**: Cookies, Header, Body from Request and Response. * Supports Markdown Table, CSV, and Raw Request & Response. ![Proxyman request context menu with the Copy as submenu showing headers, body, Markdown Table and CSV options](https://proxyman.com/docs/assets/Screenshot%202026-08-25%20at%2013.40.11.png) --- Source: https://proxyman.com/docs/basic-features/custom-previewer-tab # Custom Previewer Tab > Add Proxyman Custom Previewer Tabs to show a request or response body as JSON, Protobuf, HTML or MessagePack, or to add the Connection Log tab. ## 1. What's it? Custom Previewer Tabs let you add extra tabs to the Request and Response panels. Each tab always renders the content in one format. This handy tool helps in the following cases: * Format the BODY as **JSON**, but the Content-Type isn't `application/json` * Format the body as **Protobuf**, but the Content-Type isn't `application/x-protobuf` * Render an HTML page in a Web View * **Beautify** the minified files (HTML, CSS, JS) * Multipart/form-data * Try to format the body as the selected type regardless of the `Content-Type` * Convert MessagePack (msgpack) to JSON * [Code Generator](https://proxyman.com/docs/advanced-features/code-generator) to Swift, Node, Javascript, cURL, ... * GraphQL Query Prettier * [Connection Log](https://proxyman.com/docs/basic-features/connection-log) to inspect DNS, TCP, TLS, and HTTP details ![Proxyman Custom Body Previewer Tabs window with Request and Response checkboxes, Connection Log checked, and Add Custom Tabs](https://proxyman.com/docs/assets/proxyman-custom-previewer-tab-window.jpg) _Select Custom Tabs for Request / Response Panel_ > **Note:** The selected custom tabs are added to the right side of the Request or Response view ## 2. How to use it? To open the Custom Previewer Tab window: 1. Click the "+" button on the Request/Response tab bar, or go to **Tools** → **Custom Previewer Tab…** 2. Check or uncheck a checkbox to show or hide your custom tab 3. The new tab appears on the Request or Response panel ✅ ### 2.1 Server-Sent Events and OpenAI Tabs From Proxyman 5.22.0 or later, Proxyman supports: * **SSE** tab for Server-Sent Events from OpenAI endpoints: Auto-prettify the inline JSON of each data event * **OpenAI** tab: Auto-merge the streamed content and show the final result, similar to the output in your chat view. ### 2.2 Connection Log * **Connection Log** shows connection info for the selected request, including DNS lookups, TCP connections, TLS negotiation, certificates, and HTTP headers. * Click **+** in the Request tab bar. Under **Request**, check **Connection Log** to show it or uncheck it to hide it. * The tab appears next to **Summary** in the Request panel. It is enabled by default, and Proxyman remembers your choice. * See the [HTTP/2 guide](https://proxyman.com/docs/basic-features/http2) for a sample log, or the [Connection Log guide](https://proxyman.com/docs/basic-features/connection-log) for all fields. ## 3. ⚡️ Advanced: Create a custom Tab with the Scripting Tool * ✅ Show your own data on your tab * Useful when you want to decode your body or show part of the body in your own tab ### How to use 1. Click the "+" button on the Request/Response tab bar, or go to **Tools** → **Custom Previewer Tab…** 2. Click the **Add Custom Tabs** button 3. Select the Request or Response panel and set a name for your tab 4. Click the "..." button to show the JavaScript code 5. Open **Scripting** → **Script List…**, create a new [script](https://proxyman.com/docs/scripting/script), and use this code to display your own data ![Proxyman Script Editor setting customPreviewerTabs values in onRequest and onResponse](https://proxyman.com/docs/assets/343035431-1a336092-5c50-4e23-afbb-9a41f9679bb9.jpg) _Write your code to display data_ 6. Done ![Proxyman showing custom body and json tabs filled with data from a script](https://proxyman.com/docs/assets/343035436-dc7e6346-9ac6-4601-b07a-8294de2c4a02.jpg) _Display your data on a new tab_ ## 4. Examples ### Force render JSON TreeView Proxyman supports JSON Tree View for better visualization You can show or hide a column by right-clicking the column header ### Force render HTML Page Check **HTML Webview** in the Response panel list to render an HTML response as a web page, instead of reading the raw HTML. ### Beautify the Javascript files Check **Auto beautify the minified content** at the bottom of the Custom Previewer Tab window. Proxyman then formats minified HTML, CSS and JavaScript so you can read it. ## Learn more * [Debug OpenAI Server-Sent Events with Proxyman](https://proxyman.com/posts/debug-server-sent-event-openapi-endpoint-with-proxyman) * [Preview multipart/form-data bodies from HTTP requests and responses](https://proxyman.com/posts/2021-06-24-preview-multipart-formdata) --- Source: https://proxyman.com/docs/basic-features/custom-header-column # Custom Header Column > Add custom columns in Proxyman from request or response headers, query parameters, and JSON body values to tell similar requests apart at a glance. ## 1. What's it? The Custom Header Column feature lets you add your own columns to the main table view. It's similar to the [custom columns in Chrome DevTools](https://developer.chrome.com/docs/devtools/network/reference#custom-columns). ## 2. Benefit * Show a request or response header as a column in the table. * **Tell requests apart when they have the same URL but different headers.** * Resize, sort, and reorder the columns. * Proxyman remembers your columns and restores them in your next session. ## 3. Custom Column You can create a custom column from: * ✅ Request or response header, e.g. Content-Type, X-Key, ... * ✅ Query parameter of the request, e.g. name, id, ... * ✅ JSON body with jq or JSON Path, e.g. $.data.user.name (Proxyman 6.17.0 or later) ![Custom Columns window with request and response lists, and Header, Query and JSON Body columns turned on](https://proxyman.com/docs/assets/Screenshot%202026-08-25%20at%2013.13.07.jpg) ## 4. How to use it? 1. Open **Tools** → **Customize Columns…** 2. Click the **+** button under the Request or Response list. 3. Choose Header, Query, or JSON Body. Enter the name or expression, then click **Add**. ![Proxyman sheet that adds a custom column from a JSON body value with the JSON Path option selected](https://proxyman.com/docs/assets/Screenshot%202026-08-25%20at%2013.13.17.png) To learn how to query JSON data with JSON Path or jq, read: * [**JSON Path**](https://proxyman.com/docs/basic-features/jsonpaths) * [**jq**](https://proxyman.com/docs/basic-features/jq) ## 5. Built-in GraphQL Query Column Proxyman can show the query name of each GraphQL request in the **Query Name** column. Right-click the table header and select **Query Name (GraphQL)** to show it. ![Proxyman table with a Query Name column showing GetUser, ListPosts and CreatePost for GraphQL requests](https://proxyman.com/docs/assets/proxyman-graphql-query-name-column.jpg) _GraphQL Query Name column_ ## Learn more * [Manage header columns on the main table view](https://proxyman.com/posts/2022-06-18-Tips-Manage-custom-columns-on-the-main-table-view) --- Source: https://proxyman.com/docs/basic-features/regex # Regex (Regular Expression) > Use Wildcard and Regex matching rules in Proxyman tools such as Map Local and Breakpoint, and test your rule against sample URLs before you save it. ## 1. What's it? From version 2.3.0, Proxyman supports **Wildcard** and **Regex** (match whole words) when you define matching rules for all debugging tools: * [Map Local](https://proxyman.com/docs/advanced-features/map-local) * [Map Remote](https://proxyman.com/docs/advanced-features/map-remote) * [Block List](https://proxyman.com/docs/advanced-features/blacklist) and [Allow List](https://proxyman.com/docs/advanced-features/whitelist) * [Breakpoint](https://proxyman.com/docs/advanced-features/breakpoint) * [Protocol Buffers (Protobuf)](https://proxyman.com/docs/advanced-features/protobuf) * [Reverse Proxy](https://proxyman.com/docs/advanced-features/reverse-proxy) * [Network Conditions](https://proxyman.com/docs/advanced-features/network-throttling) * ... It helps you define exactly which requests trigger the tool. ![Proxyman Map Remote rule list with one Regex rule and two Wildcard rules in the Matching Rule column](https://proxyman.com/docs/assets/proxyman-map-remote-rules.jpg) _Wildcard and Regex rules_ ## 2. Test your URL (New feature 🎉) From Proxyman v4.8.0, you can quickly test your rule (Wildcard or Regex). * Quickly test and try out your Wildcard or Regex rule. * **Save time**: You don't need to go back and forth to check your URL. * Make fewer mistakes. ![Proxyman Test Rules window checking the wildcard http://localhost:3000/* against three URLs, Matched or Not Matched](https://proxyman.com/docs/assets/proxyman-test-rules-window.jpg) _Test a rule against your URLs_ #### How to use it? 1. Open any debugging tool (Breakpoint, Map Local, ...) and create a new rule. 2. Click the **Test your Rule** button. The Test Rules window opens. 3. Add your rule and the URLs you want to check. * :white\_check\_mark: Matched: Your URL matches your rule. * :warning: Not Matched: Your URL doesn't match your rule. You might need to rewrite your Wildcard or Regex rule. ## 3. Wildcard Proxyman supports two simple Wildcard characters: `*` and `?` | Wildcard | Purpose | | -------- | -------------------------------------------------------------------- | | `*` | The asterisk in a wildcard matches any character zero or more times. | | `?` | A question mark matches a single character once. | For instance: * http://proxyman.io/v1/\* * https://myserver.com/v?/\* ## 4. Regex Proxyman also supports Regex. * Make sure your regex **matches the whole URL**. * A **partial match** counts as not matching. * Make sure you **escape characters** properly: slash (/), dot (.), etc. For instance: | Regex | Matched URL Examples | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | https:\\/\\/proxyman\\.io.\* |

https://proxyman.io
https://proxyman.io/v1/data?id=123
https://proxyman.io/pricing

| | ^(http\|https):\\/\\/www\\.google\\.com.\* |

http://www.google.com
http://www.google.com/user?id=proxyman
https://www.google.com

| | ^(http\|https)?:\\/\\/www\\.google\\.com\\/v\[0-9]?\\/build\\?query=proxyman |

http://www.google.com/v1/build?query=proxyman
www.google.com/v2/build?query=proxyman

| You can use [regex101](https://regex101.com/) to check that your regex matches the whole URL. ![regex101 test with a regex that fully matches three google.com URLs](https://proxyman.com/docs/assets/1.png) > **Note:** Proxyman uses Apple's NSRegularExpression. Check the [**Regex** **metacharacters, operators and flags**](https://developer.apple.com/documentation/foundation/nsregularexpression#1965590) in the Apple Developer documentation to see which ones are supported. > **Note:** Check your regex on [regex101.com](https://regex101.com) and make sure it fully matches the given URL. * Select **Use Regex** when you create a rule. > **Note:** With regular expressions, `?` and `*` mean something different than in wildcards. The wildcard `?` is the regex `.` and the wildcard `*` is the regex `.*` --- Source: https://proxyman.com/docs/basic-features/filter-json-response # Filter JSON Response > Filter JSON responses in Proxyman with text search, regex, JSONPath and jq, or show only the keys and values that match in the Treeview tab. You can quickly filter a JSON response in these ways: ## 1. Filter on JSON Previewer * Press **⌘F** in the Body tab to search * Supports Regex * Jump to the next match ## 2. JSONPath Proxyman supports [JSONPath](https://github.com/json-path/JsonPath#path-examples) to quickly query data in a JSON document. ![Proxyman Treeview tab with the JSON Path $.slideshow.slides[*].title returning two slide titles](https://proxyman.com/docs/assets/proxyman-treeview-jsonpath-filter.jpg) _Filter JSON with JSON Path_ Read the JSONPath page to learn the syntax. - [JSONPath](https://proxyman.com/docs/basic-features/jsonpaths) You can also filter JSON with jq. Read the [jq](https://proxyman.com/docs/basic-features/jq) page. ## 3. Search in the Treeview * Press **⌘F** in the Treeview tab and choose a mode: Search, Filter, JSON Path, or jq. * **Search** highlights the keys and values that contain the search text. ## 4. Filter by Keys or Values * **Filter** shows only the nodes whose key or value contains the search text. ![Proxyman Treeview filter mode menu with Search, Filter, JSON Path and jq options](https://proxyman.com/docs/assets/proxyman-treeview-filter-mode.jpg) _Pick a filter mode_ --- Source: https://proxyman.com/docs/basic-features/highlight-by-color-and-add-comment # Highlight by Color and Add Comment > Highlight requests in Proxyman with colors or strikethrough, add comments, then filter by color or comment and share the log with your team. ## 1. What's it? You can: * **Highlight** one or more requests with a **color** (Red, Orange, Yellow, Green, Teal, Blue, Indigo, Purple, Pink, Brown, Gray) * Add ~~Strikethrough~~ * Add a comment * Filter by color or comment (⌘F) * Export with colors and comments. Colors are kept only in the Proxyman Log format. ![Proxyman request list with green and red rows, one strikethrough request, and notes in the Comment column](https://proxyman.com/docs/assets/proxyman-highlight-color-comment.jpg) _Colored rows and comments_ ## 2. Benefit? * Mark failed or successful requests with eye-catching colors * Add comments during development * Share them with your colleagues (color and comment) * Quickly filter requests by color or comment ## 3. How to use 1. Right-click a request 2. Select **Highlight** and choose a color To add a comment, right-click a request and select **Add Comment…** (⌘L). ![Proxyman request context menu with the Highlight submenu showing 11 colors, Strikethrough and Reset](https://proxyman.com/docs/assets/Screenshot%202026-08-25%20at%2013.37.19.png) --- Source: https://proxyman.com/docs/basic-features/import-export-settings # Import / Export Settings > Back up and share Proxyman settings and debugging rules, import rules from Proxyman or Charles Proxy, and open Charles Proxy session files. ## 1. Import Settings From Proxyman 2.26.0, you can import tool settings from colleagues who use **Proxyman** or **Charles Proxy**. To import settings, go to **Tools** → **Import / Export Settings** → **Import**, then choose **From Proxyman** or **From Charles Proxy**: * **From Proxyman** → **From Backup File**: Import a `.config` backup file made with **Export (Backup)**. Choose **Override** to replace your current settings, or **Append** to add to them. * **From Proxyman** → **Single Rule (Deprecated)**, or **From Charles Proxy**: Select the tool you want to import. ![Tools menu of an older Proxyman version with Import Settings submenus for Proxyman and Charles Proxy](https://proxyman.com/docs/assets/Screen_Shot_2021-05-17_at_09_11_44.png) You can import settings for these tools: ### Proxyman * SSL Proxying List * Block List * Allow List (White List) * Map Local * Map Remote * Breakpoint * Network Conditions * Scripting * Reverse Proxy * DNS Spoofing * Protobuf ### Charles Proxy * SSL Proxying List * Block List * Allow List (White List) * Map Local * Map Remote * Breakpoint * Reverse Proxy * DNS Spoofing ## 2. Export Settings You can also export your tool settings and share them with your colleagues. ### Back up all settings From Proxyman 6.4.0, you can save your app settings and debugging tools in one backup file: 1. Go to **Tools** → **Import / Export Settings** → **Export (Backup)…** 2. Select **App Settings** and the debugging tools you want to include 3. Click **Export** and save the `.config` file ### Export rules from one tool 1. Open the tool you want to export 2. Select the rules 3. Right-click → **Export Settings…** ![Block List window with a rule selected and Export Settings in the context menu](https://proxyman.com/docs/assets/Screen_Shot_2021-05-17_at_09_16_41.png) ## 3. Open Charles Proxy Log File (\*.chls) Proxyman can open Charles Proxy log files that you export from the Charles Proxy app. Read the Charles Proxy Converter page. - [Charles Proxy Converter](https://proxyman.com/docs/advanced-features/charles-proxy-converter) ## Learn more * [Migrate from Charles to Proxyman](https://proxyman.com/posts/2020-07-03-Migrate_From_Charles_To_Proxyman) * [Hidden features from Proxyman: import Charles Proxy log files](https://proxyman.com/posts/2021-07-03-hidden-features-from-proxyman) --- Source: https://proxyman.com/docs/basic-features/multipart-form-data-previewer # Multipart Form-Data Previewer > Inspect each part of a multipart/form-data request in the Proxyman Multipart tab, preview its content, and save any part to a file on your Mac. ## 1. What's it? From Proxyman 2.27.0, Proxyman shows a multipart/form-data body as a table in the **Multipart** tab of the Request panel. ![Proxyman Multipart tab listing the parts of a POST request with Preview and Export buttons on each row](https://proxyman.com/docs/assets/proxyman-multipart-form-data-tab.jpg) _Multipart tab in the Request panel_ ## 2. Benefit * Display each part of the multipart/form-data body * Preview a part or save it to a file ## Learn more * [Preview multipart/form-data body from HTTP request and response](https://proxyman.com/posts/2021-06-24-preview-multipart-formdata) --- Source: https://proxyman.com/docs/basic-features/jsonpaths # JSONPath > Query JSON request and response bodies in Proxyman with JSONPath. Learn the syntax, filter operators, and path examples you can copy. ## 1. What's it? JSONPath is a query language that quickly filters JSON data. In Proxyman, you can use it in the JSON tab, the Treeview tab, and [custom columns](https://proxyman.com/docs/basic-features/custom-header-column). ![Proxyman JSON tab filtering a response body with a JSON Path expression](https://proxyman.com/docs/assets/Screenshot%202026-08-25%20at%2014.04.30.jpg) ## 2. How to use 1. In the Request or Response panel, click the **+** button 2. Select **JSON** to add the JSON tab 3. The filter bar appears above the JSON body 4. Select the **JSON Path** or **jq** filter mode ## 3. Syntax | Operator | Description | | ------------------------- | ------------------------------------------------------------------- | | `$` | The root element to query. This starts all path expressions. | | `@` | The current node being processed by a filter predicate. | | `*` | Wildcard. Available anywhere a name or numeric are required. | | `..` | Deep scan. Available anywhere a name is required. | | `.` | Dot-notated child | | `['' (, '')]` | Bracket-notated child or children | | `[ (, )]` | Array index or indexes | | `[start:end]` | Array slice operator | | `[?()]` | Filter expression. The expression must evaluate to a boolean value. | ### Filter Operators Filters are logical expressions used to filter arrays. A typical filter would be `[?(@.age > 18)]` where `@` represents the current item being processed. | Operator | Description | | -------- | -------------------------------------------------------------------- | | == | left is equal to the right (note that 1 is not equal to '1') | | != | left is not equal to the right | | < | left is less than right | | <= | left is less or equal to the right | | > | left is greater than right | | >= | left is greater than or equal to the right | | =\~ | left matches regular expression \[?(@.name =\~ /foo.\*?/i)] | | in | left exists in right \[?(@.size in \['S', 'M'])] | | nin | left does not exist in right | | subsetof | left is a subset of right \[?(@.sizes subsetof \['S', 'M', 'L'])] | | anyof | left has an intersection with right \[?(@.sizes anyof \['M', 'L'])] | | noneof | left has no intersection with right \[?(@.sizes noneof \['M', 'L'])] | | size | size of left (array or string) should match right | | empty | left (array or string) should be empty | ### Path Examples Given the JSON Data. ```javascript { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } }, "expensive": 10 } ``` | JsonPath | Result | | --------------------------------------- | ------------------------------------------------------------ | | $.store.book\[\*].author | The authors of all books | | $..author | All authors | | $.store.\* | All things, both books and bicycles | | $.store..price | The price of everything | | $..book\[2] | The third book | | $..book\[-2] | The second to last book | | $..book\[0,1] | The first two books | | $..book\[:2] | All books from index 0 (inclusive) until index 2 (exclusive) | | $..book\[1:2] | All books from index 1 (inclusive) until index 2 (exclusive) | | $..book\[-2:] | Last two books | | $..book\[2:] | All books from index 2 (inclusive) to the end | | $..book\[?(@.isbn)] | All books with an ISBN number | | $.store.book\[?(@.price < 10)] | All books in store cheaper than 10 | | $..book\[?(@.price <= $\['expensive'])] | All books in store that are not "expensive" | | $..book\[?(@.author =\~ /.\*REES/i)] | All books matching regex (ignore case) | | $..\* | Give me everything | | $..book.length() | The number of books | ## Reference * [Jayway JsonPath on GitHub](https://github.com/json-path/JsonPath) --- Source: https://proxyman.com/docs/basic-features/jq # JQ > Filter and transform JSON request and response bodies in Proxyman with jq in the JSON and Treeview tabs. Learn how to open the JSON tab and use jq. ## 1. What's it? * jq is a small language for JSON data. It works like sed does for text: you can slice, filter, map, and transform JSON data. * Available on Proxyman 5.24.0 or later > **Tip:** > > - You can use the jq filter in the JSON tab and the Treeview tab. To add the JSON tab, click the + button on the Request or Response toolbar and select JSON. ![Proxyman Treeview tab in jq mode with .slideshow.slides[] | {title, type} returning the title and type of each slide](https://proxyman.com/docs/assets/proxyman-treeview-jq.jpg) _Filter JSON with jq_ ## 2. Syntax * Read the [jq manual](https://jqlang.org/manual/#basic-filters) to learn how to write jq filters. * You can also use jq to create a [custom column](https://proxyman.com/docs/basic-features/custom-header-column) from a JSON body. --- Source: https://proxyman.com/docs/basic-features/customize-toolbar # Customize Toolbar > Customize the Proxyman toolbar on macOS with buttons that turn tools such as Breakpoint, Map Local, and Scripting on or off with one click. ## 1. What's it? From Proxyman 2.32.0, you can customize your toolbar to fit your needs. You can add these tool buttons to your toolbar: * Proxy Overridden * Block List * Allow List * Breakpoint * Map Local * Map Remote * Reverse Proxy * Network Throttling * Scripting * No Caching * SSL Proxying * External Proxy Each tool button turns its tool on or off. ![Customize Toolbar sheet of an older Proxyman version with tool toggle buttons such as Breakpoint and Scripting](https://proxyman.com/docs/assets/Screen_Shot_2021-08-28_at_17_15_16.png) ## 2. How to use it? You can open the Customize Toolbar sheet from: * Right-click the toolbar → **Customize Toolbar…** * **Tools** menu → **Customize Toolbar…** > **Note:** Customize Toolbar works on every macOS version that Proxyman supports (macOS 14 Sonoma or later). --- Source: https://proxyman.com/docs/basic-features/localization # Localization > Change the Proxyman app language to English, Chinese, Japanese, Portuguese, or Spanish, and help improve the app translations on GitHub. ## 1. What's it? Proxyman is localized, so the whole app UI can show in your language. The current languages are: * English (Default) * Chinese - Simplified * Japanese * Portuguese - Brazil * Spanish - Latin America Japanese, Portuguese, and Spanish are available from Proxyman 6.17.0. ## 2. How to change the app language? By default, Proxyman uses your macOS system language. To change it: 1. Open Proxyman **Settings** (⌘,) → **General** → **App Language** and select a language. Proxyman offers to open System Settings for you. 2. In **System Settings** → **General** → **Language & Region**, under **Applications**, add Proxyman and choose a language. 3. Relaunch Proxyman to apply the change. ![Proxyman App Language menu with English, Chinese Simplified, Japanese, Portuguese Brazil and Spanish Latin America](https://proxyman.com/docs/assets/proxyman-settings-app-language.jpg) _Pick an app language_ ## 3. Improve localization? If you find a poor translation in your language, please help us improve it on GitHub at [ProxymanApp/proxyman-localization](https://github.com/ProxymanApp/proxyman-localization). --- Source: https://proxyman.com/docs/basic-features/quick-preview # Quick Preview > Use Proxyman Quick Preview on selected text to prettify JSON or XML, decode Base64 and JWT tokens, convert timestamps, and show key-value tables. ## 1. What is it? Quick Preview lets you preview selected text anywhere in the app. * Beautify inline JSON * Decode Base64 strings * Display key & value text as a table * Decode JWT tokens * In the Body and Raw tabs, you can also prettify XML and convert timestamps ![Proxyman Quick Preview decoding a JWT selected in the Raw tab into Header, Payload and Signature](https://proxyman.com/docs/assets/proxyman-quick-preview-jwt.jpg) _Decode a JWT with Quick Preview_ ## 2. How to use it? 1. Select any text in the app, e.g. in the Body tab or the Raw tab 2. Right-click to show the context menu 3. Choose a **Text Selection** mode, for example **Text Selection: Decode Base64**. In other text views, the modes are under **Text Selection: View as**. ![Proxyman Raw tab right-click menu with Text Selection options: Prettify JSON, Decode Base64, Decode JWT and more](https://proxyman.com/docs/assets/proxyman-quick-preview-raw-tab-menu.jpg) _Quick Preview on the Raw tab_ --- Source: https://proxyman.com/docs/basic-features/command-palette # Command Palette > Open the Proxyman Command Palette with ⌘P to search and toggle debugging tools, open setup guides, and pin the actions you use most. ## 1. What's it? The global Command Palette helps you: * Quickly search debugging tools * Turn debugging tools on or off * Open setup guides for iOS devices, iOS Simulators, Android devices, and Android Emulators * Pin your most-used actions ![Proxyman Command Palette searching for simulator, listing iOS, tvOS and visionOS Simulator and Flutter setup guides](https://proxyman.com/docs/assets/proxyman-command-palette.jpg) _Search the Command Palette_ > **Tip:** Press ⌘P, or select **View** → **Show Command Palette**, to open the Command Palette. In Proxyman 6.0.0 to 6.10.0, the shortcut is ⌘⇧P. > **Warning:** Command Palette is available on Proxyman for macOS 6.0.0 or later. ## 2. Missing your shortcut? If you can't find your shortcut in the Command Palette, please request it on our [GitHub public issue tracker](https://github.com/ProxymanApp/Proxyman/issues). ## Learn more * [Useful shortcuts that boost your productivity](https://proxyman.com/posts/2019-08-20-Useful-shortcuts-that-boost-your-productivity) --- Source: https://proxyman.com/docs/advanced-features/network-extension # Network Extension > Use Proxyman Network Extension to capture HTTP and HTTPS traffic from every app on your Mac, including apps and scripts that ignore proxy settings. ## 1. What's it? Network Extension captures HTTP/HTTPS traffic from apps on your Mac, including apps that ignore the system proxy. It's built on Apple's [transparent proxy Network Extension API](https://developer.apple.com/documentation/networkextension/netransparentproxyprovider). It runs as a macOS system extension, signed with our TablePlus Inc Developer ID certificate and notarized by Apple. It works similarly to Network Capture mode in Fiddler Everywhere and Local Capture mode in mitmproxy. You don't need to set a proxy in each app. > **Warning:** Network Extension is BETA and off by default. It requires Proxyman PRO, the direct Proxyman edition, and macOS 26 or later. It is not available in Setapp. ![Proxyman captures cURL HTTPS requests without the --proxy flag](https://proxyman.com/docs/assets/proxyman_network_extension.jpeg) _Capture cURL requests without the --proxy flag_ ## 2. Problem Regular proxy mode relies on apps sending their requests through the proxy. * Some apps and scripts ignore macOS's system proxy, so Proxyman misses their requests. * NodeJS, Ruby, and Python libraries may need separate proxy settings, code changes, or Automatic Setup. * Setting up each app or library by hand takes time and can lead to mistakes. ## 3. Benefits * Capture traffic from apps and scripts that ignore proxy settings. * Skip manual proxy setup for each app. * Use existing tools such as Map Local, Breakpoint, and Scripting on captured requests. ## 4. How to install the Network Extension? 1. Turn on Network Extension in one of two ways: * Open Proxyman -> **Settings** -> **Network Extension**. Turn on **Enable Network Extension**. Click **Install and Enable** if shown. ![Proxyman Settings with the Network Extension pane and the Enable Network Extension toggle](https://proxyman.com/docs/assets/Screenshot%202026-10-01%20at%2019.56.42.jpg) _Turn on Network Extension in Settings_ * Or click the status bar at the top of the main window (Proxyman | Listening on ...) and turn on **Network Extension**. 2. Open **System Settings** -> **General** -> **Login Items & Extensions**. Under **Extensions**, select **By Category** -> **Network Extensions**, then enable Proxyman. 3. When macOS asks to add the network configuration, click **Allow**. ![Enable the Proxyman toggle in Network Extensions](https://proxyman.com/docs/assets/install_proxyman_network_extension_step_2.jpeg) _Allow Proxyman Network Extension_ 4. Wait until Proxyman shows "Capturing HTTP and HTTPS from local applications." ## 5. How to use? 1. Keep Proxyman open with Network Extension enabled. 2. Network Extension now captures traffic from the apps on your Mac and sends it to Proxyman. 3. To read HTTPS content, [install and trust the Proxyman certificate](https://proxyman.com/docs/debug-devices/macos), then enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the app or domain. 4. Make a new request from your app, browser, or script. The request appears in Proxyman. If an app was already running before you enabled the extension, restart it to capture new connections. To stop capture without uninstalling, turn off **Enable Network Extension** in Settings. ## 6. Troubleshooting ### SSL errors in NodeJS, Ruby, or Python These runtimes may not trust Proxyman's self-signed certificate, even when you trust it in macOS. Network Extension captures their traffic, but certificate trust still needs setup. Use [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup) to set up certificate trust for supported libraries: 1. Open Proxyman -> **Setup** -> **Automatic Setup**. 2. Click **Open New Terminal** and accept the permission prompt if needed. 3. Run your script or restart your server in that new terminal. > **Tip:** If you're using [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup) or [Manual Setup](https://proxyman.com/docs/automatic-setup/manual-setup), you can turn off **Enable Network Extension** in **Settings** -> **Network Extension**. Keep running your script or server in the terminal configured by that setup. If the error continues, check the [Automatic Setup troubleshooting guide](https://proxyman.com/docs/automatic-setup/troubleshooting). ## 7. How to uninstall the Network Extension? 1. Open Proxyman -> **Settings** -> **Network Extension**. 2. Click **Uninstall**, then confirm. 3. Enter your Mac password if asked, and restart your Mac if requested. Uninstalling stops capture and closes connections using the extension. It also removes the network configuration. ## 8. Command-line Use `proxyman-cli network-extension` to read status, install, uninstall, enable, disable, or retry. Proxyman must be open. Use `install` to install without turning capture on, or `enable` to start capture and install the extension if needed. macOS approval or a restart may still be required. See the [Network Extension command-line guide](https://proxyman.com/docs/command-line#16-network-extension) for commands, JSON status fields, and exit codes. ## Learn more * [Introducing Network Extension: capture Mac traffic without proxy setup](https://proxyman.com/posts/2026-10-06-introducing-network-extension) --- Source: https://proxyman.com/docs/advanced-features/repeat # Repeat > Use Proxyman Repeat to resend a captured HTTP or HTTPS request with the same headers and body, so you can check the latest server response fast. ## 1. What's it? The Repeat tool sends a captured HTTP request again with the same HTTP headers and body. You can see the new response without going back to your browser or client app. ## 2. What's it for? * Quickly send an HTTP/HTTPS request again to see the newest response from the server. * Test a change on your server without repeating the request by hand. > **Note:** The Repeat tool only supports HTTP/HTTPS requests. Repeating WS/WSS traffic may fail. > **Note:** The Breakpoint, Map Local, and Scripting tools can modify repeated requests if they match any rules. ## 3. How to use * Right-click on one or more requests -> **Repeat** ![Proxyman right-click menu on a captured request with Repeat (⌘⏎) highlighted](https://proxyman.com/docs/assets/proxyman-repeat-request-context-menu.jpg) _Right-click > Repeat_ > **Note:** ⌘ ⏎ : Repeat the selected request. ## 4. Settings * **Request Timeout**: Open the [Compose](https://proxyman.com/docs/advanced-features/compose) window -> click the **⋯** button at the bottom -> **Request Timeout**. Pick 15, 30, or 60 seconds, a custom value, or **0 (No Timeout)**. Repeated requests use the same timeout. Available on Proxyman 4.13.0 or later. * **Use No-Cache on Repeated Requests**: In **Settings** -> **Tools**. Repeated requests ignore caching and always fetch the response from the server. --- Source: https://proxyman.com/docs/advanced-features/edit-and-repeat # Edit & Repeat > Use Proxyman Edit & Repeat to change the URL, query, headers, or body of a captured HTTP request, send it again, and check the new response. ## 1. What's it? Edit & Repeat is a handy tool to test an endpoint directly in the Proxyman app, without making a new request from your browser or client app. * Quickly change the **Query**, **Header**, or **Body** of the selected request and test the response from the server. * Easily reproduce a server bug with a different set of parameters. * Supports Form and JSON formats. * Edit the Raw Message. * Review the response data on the right panel (Proxyman 3.6.0+). ![Proxyman Compose window with an edited POST request JSON body on the left and the 201 Created response on the right](https://proxyman.com/docs/assets/proxyman-compose-json-body.jpg) _Edit the request and check the response_ ## 2. How to use it? 1. Select your request -> Right-click -> **Edit and Repeat…** (⌥⌘⏎) 2. Proxyman keeps the request data (Header, URL, Query, Body), so it's ready to edit. ![Proxyman right-click menu on a captured request with Edit and Repeat... (⌥⌘⏎) highlighted](https://proxyman.com/docs/assets/proxyman-edit-and-repeat-context-menu.jpg) _Right-click > Edit and Repeat_ --- Source: https://proxyman.com/docs/advanced-features/compose # Compose new Request > Use Proxyman Compose to build and send HTTP or HTTPS requests to your API, import cURL commands, and inspect the response, like a simple Postman. ## 1. What's it? The Compose tool helps developers: * Compose an HTTP/HTTPS request and send it to your service. It's similar to Paw, Insomnia, and Postman. * Quickly test your APIs without your client app. * Supports Header, Query, URL, Form, and JSON Body. * Supports Raw Message. * Supports multipart body. * Preset templates, such as Empty Request, GET with Query, and POST with JSON or Form. > **Note:** You can reuse your request data for new requests. Please check out the [Edit & Repeat](https://proxyman.com/docs/advanced-features/edit-and-repeat) page. ## 2. How to use You can open the tool by either: * Click the Compose button on the main toolbar * **Tools** -> **Compose Request…** (⌥⌘C) 1. Enter the URL 2. Select the HTTP Method 3. Modify the Header, Query, Body, or Raw Message 4. Click the **Send** button. ![Proxyman Compose window sending a POST request with a JSON body and getting a 201 Created JSON response](https://proxyman.com/docs/assets/proxyman-compose-json-body.jpg) _Send a POST request with a JSON body_ ## 3. Template Click the **Template** button at the bottom of the Compose window to start from a preset: * Empty Request * GET with Query * QUERY with Body * POST with JSON * POST with Form * POST with Multiparts * WebSocket * Import from cURL… ![Proxyman Compose Template menu with presets such as QUERY with Body and WebSocket, and Import from cURL highlighted](https://proxyman.com/docs/assets/proxyman-compose-template-menu.jpg) _Compose templates_ ## 4. Import from cURL You can import a cURL command, for example one copied from the Network tab in Google Chrome, and send it with the Compose tool. Click **Template** -> **Import from cURL…**. > **Tip:** You can also paste your cURL command into the URL field. Proxyman tries to parse it. ## 5. History Request From Proxyman macOS 5.24.0, Proxyman stores your requests and responses in the **History** list. * ✅ Useful to preview your previous Request/Response ## 6. Settings * **Request Timeout**: Click the **⋯** button at the bottom of the Compose window -> **Request Timeout**. Pick 15, 30, or 60 seconds, a custom value, or **0 (No Timeout)**. The same timeout applies to [repeated requests](https://proxyman.com/docs/advanced-features/repeat). Available on Proxyman 4.13.0 or later. ![Proxyman Compose ⋯ menu with Request Timeout options 15, 30, 60 seconds, 0 (No Timeout), Custom...](https://proxyman.com/docs/assets/proxyman-compose-request-timeout.jpg) _Set the request timeout_ ## Learn more * [Proxyman now supports the HTTP QUERY method](https://proxyman.com/posts/2026-07-11-Proxyman-now-supports-HTTP-QUERY-method) --- Source: https://proxyman.com/docs/advanced-features/no-caching # No Caching > Use Proxyman No Caching to strip and override cache headers, so your app always gets the latest HTTP response from the server instead of a cache. ## 1. What's it? No Caching prevents the server or client from caching your requests and responses, so you always get the latest change from the server. The No Caching tool affects all HTTP requests and responses, and HTTPS traffic that has SSL Proxying enabled. ## 2. What's for? * When you would like to **see the latest HTTP Response changes** from the server or client and ignore all caching layers. ## 3. How it works The No Caching tool changes every request and response by adding or removing the caching HTTP headers in the following table. | HTTP Message | Remove | Add | | ------------ | -------------------------------------------- | ---------------------------------------------------- | | Request | **If-Modified-Since** and **If-None-Match** | **Pragma: no-cache** and **Cache-control: no-cache** | | Response | **Expires**, **Last-Modified,** and **ETag** | **Expires: 0** and **Cache-Control: no-cache** | ## 4. How to use * Enable it in **Tools** menu -> **No Caching** ![Proxyman Tools menu with No Caching (⌥⌘N) checked and highlighted](https://proxyman.com/docs/assets/proxyman-tools-menu-no-caching.jpg) _Tools menu > No Caching_ * When it's on, a **No Caching** badge shows at the bottom right of the main window. ![No Caching badge in the Proxyman status bar next to memory and network speed](https://proxyman.com/docs/assets/proxyman-no-caching-status-badge.jpg) _No Caching badge_ > **Note:** **⌥⌘N:** Toggle the No Caching Tool. --- Source: https://proxyman.com/docs/advanced-features/breakpoint # Breakpoint > Use Proxyman Breakpoint to pause HTTP requests and responses and edit the URL, headers, status code, or body on the fly before they continue. ## 1. What's it? Breakpoint is a handy tool to help developers edit the content of the Request and Response **on the fly**. You can set a breakpoint on the **Request**, the **Response**, or both. ![Proxyman Breakpoint rule editor with a matching rule and the Request and Response checkboxes](https://proxyman.com/docs/assets/Screenshot%202026-06-28%20at%2019.24.05.jpg) _Create a Breakpoint rule_ > **Note:** If you're using the [Atlantis Framework](https://proxyman.com/docs/atlantis/atlantis-for-ios), you can't use Breakpoint. Please use a normal proxy instead. ## Video [Video: Modify requests and responses with Breakpoint](https://proxyman.com/videos/breakpoint-tool) (30 seconds) ## 2. Main features The Breakpoint tool stops an outgoing request or an incoming response, so you can modify its data. * Modify the Request URL, including the Scheme, Host, Path, Port, HTTP Method * Modify HTTP Headers of Request/Response * Modify Query or Form entry from Requests. * Modify Authorization/Cookie/Set-Cookie Headers. * Modify HTTP Body of Request/Response * Change Response HTTP Status Code. ![Proxyman Breakpoint window paused on a POST request with editable headers and the Apply & Execute button](https://proxyman.com/docs/assets/proxyman-breakpoint-window-edit-request.jpg) _Modify the headers, URL, status code, and body_ ### Raw HTTP Message From Proxyman macOS 6.12.0 or later, you can switch to the Raw tab to modify the Request/Response HTTP message. It lets you edit all the data in one place. ![Proxyman Breakpoint Raw tab with a valid POST request message, headers and JSON body](https://proxyman.com/docs/assets/proxyman-breakpoint-raw-tab.jpg) _Edit the raw HTTP message_ ### Breakpoint Actions | Action | Meaning | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Continue Original (⌘.) | Ignore your changes and continue the Request/Response with the original data | | Drop Connection (⌘\\) | Abort the breakpoint and stop the connection. Use the arrow next to it -> **Abort Mode** to return a 429 or 503 status instead | | Apply & Execute (⌘⏎) | Send the Request/Response with your changes | > **Note:** Check out the Breakpoint tutorial: [Use Breakpoint to intercept and edit requests and responses on an iOS app](https://proxyman.com/posts/2019-09-15-Use-Breakpoint-to-intercept-and-edit-request-response-on-iOS-app) ## 3. Breakpoint by the Scripting Tool ✅ If you would like to modify requests automatically, use the [Scripting](https://proxyman.com/docs/scripting/script#1-whats-it) tool. It gets the same result as Breakpoint, but in a more flexible way, by writing JavaScript code. Please check out the [Scripting snippet code](https://proxyman.com/docs/scripting/snippet-code#2-common-on-request-and-response) to see how to use Scripting for Breakpoint. ## 4. Breakpoint with GraphQL Requests From Proxyman 2.27.0+, Breakpoint can work with GraphQL requests by a specific QueryName. Please check out the following GraphQL document. - [GraphQL](https://proxyman.com/docs/advanced-features/graphql) ## 5. How to use You can create a Breakpoint rule this way: 1. Make sure Proxyman can capture your HTTPS request first. 2. Right-click on the request -> **Tools** -> **Breakpoint…** 3. Proxyman opens the Breakpoint rule window and fills in the Matching Rule. 4. Select Breakpoint on Request, Response, or both. 5. Click **Add** to create the rule. 6. Send the request again. Proxyman opens the Breakpoint window, and you can modify the data. 7. Click **Apply & Execute** to send the request/response. ## Learn more * [Modify HTTP Request/Response with Proxyman Breakpoint Tool](https://proxyman.com/posts/2021-12-31-Modify-URL-Request-With-Breakpoint) * [How to change HTTP Response Status Code, Header, Or the Body for Testing](https://proxyman.com/posts/change-response-status-code-header-for-testing) * [Manipulate GraphQL Request with Breakpoint Tool](https://proxyman.com/posts/2023-03-16-GraphQL-Request-With-Breakpoint) --- Source: https://proxyman.com/docs/advanced-features/breakpoint-templates # HTTP Message Templates > Create Proxyman Breakpoint Templates for requests and responses, then apply a saved HTTP message in the Breakpoint Raw tab with one click. ## 1. What's it? You can create an HTTP Message Template for the Breakpoint tool and reuse it later. * Create a new HTTP Message Template for a Request: HTTP Method, URL, Headers * Create a template for a Response: Status Code, Headers * Boost your productivity when using the [Breakpoint tool](https://proxyman.com/docs/advanced-features/breakpoint#1-whats-it). ![Proxyman Breakpoint Template window with request and response templates and a raw 404 response](https://proxyman.com/docs/assets/153364144-b1a8378e-dff8-412b-a3b6-4bfad44f9d61.png) ## 2. How to create a new template? ### Create a new one 1. **Tools** menu -> **Breakpoint** -> **Breakpoint Templates…** 2. Press ⌘N to create a Request template, or ⇧⌘N to create a Response template. 3. Define your Request/Response template. ### Use the existing one 1. Create a Breakpoint rule and make sure your request/response hits the Breakpoint. 2. Click the **Raw** tab -> **Templates** -> **Save as Template...** 3. Enter a name for the template. Done. ## 3. How to use it? 1. When a request/response hits a Breakpoint, click the **Raw** tab. 2. Click **Templates** -> Request/Response -> select your template. 3. Proxyman replaces the current data with the template. ![Proxyman Breakpoint Raw tab with the Templates menu open: Requests, Response, Save as Template, Reset to the Original](https://proxyman.com/docs/assets/proxyman-breakpoint-raw-templates-menu.jpg) _Templates menu in the Breakpoint Raw tab_ ## Learn more * [How to change HTTP Response Status Code, Header, Or the Body for Testing](https://proxyman.com/posts/change-response-status-code-header-for-testing) --- Source: https://proxyman.com/docs/advanced-features/map-local # Map Local (File) > Use Proxyman Map Local to return a local file as the response for a request, with your own status code, headers, and body, so you can mock APIs fast. ## 1. What's it? The Map Local tool lets you use the content of a local file as the HTTP response to your requests. > **Note:** You can do Map Local for **GraphQL** with the Scripting Tool ([Snippet Code](https://proxyman.com/docs/scripting/snippet-code#map-local-with-graphql)) > > You can combine **Map Local with Breakpoint** to modify the content on the fly (2.16.0+) ## Video [Video: Mock API responses with Map Local](https://proxyman.com/videos/map-local) (25 seconds) ## 2. Benefits * Define a response with a Status Code, Headers, and Body, and map it to a given request. You can test edge cases without waiting for a server update. * **Mock a fake API with a local file**: Try out test APIs that are not in production yet. ![Proxyman Map Local editor for GET https://httpbin.proxyman.app/get in Local File mode with a 200 OK JSON response](https://proxyman.com/docs/assets/proxyman-map-local-editor.jpg) _Map Local editor_ ### With an HTTP Message 1. Right-click on your request in the main table -> **Tools** -> **Map Local…**. Proxyman creates a new rule with the current response. 2. Change the Status Code, Headers, and JSON Body as you like. 3. Done. 4. Send your request again. The new response is mapped. ### With a Local File * Click the **Select Local File** button and select any file. Supports Text, JSON, Binary, and Image files. ### With \ flag * Map to a given file and still set the Status Code and Response Headers. * Works with JSON, Text, Binary, Image, etc. * Make sure to set the `Content-Type` header, so your client can read the response properly. ```json HTTP/1.1 200 OK Content-Type: application/json ``` ## 3. How to use 1. Right-click on the request (which already has a response) -> **Tools** -> **Map Local…**. Proxyman creates a rule with the current response body. Proxyman saves the file in its own Map Local folder. To see or change this folder, click **More** in the Map Local window -> **Default Local File Folder**. 2. Change the response body directly in the editor. 3. Make a request and check the new response body. ![Create a Map Local rule with the current response](https://proxyman.com/docs/assets/proxyman-map-local-context-menu.jpg) _Create a Map Local rule with the current response_ ![Proxyman Map Local More menu with Default Local File Folder open: Choose Folder, Use Default Folder, Reveal in Finder](https://proxyman.com/docs/assets/proxyman-map-local-default-folder.jpg) _Default Local File Folder_ ## 4. Map Local with GraphQL Requests From Proxyman 2.27.0+, Map Local can work with GraphQL requests by a specific QueryName. Please check out the following GraphQL document. - [GraphQL](https://proxyman.com/docs/advanced-features/graphql) ## 5. Map Local with Scripting Tool ✅ If you would like to do Map Local with **complicated rules,** check out [Scripting](https://proxyman.com/docs/scripting/script#1-whats-it), since it's easier to get the same result. Please check out this [Snippet Code](https://proxyman.com/docs/scripting/snippet-code#2-common-on-request-and-response) to see how to map a local file with JavaScript code. ## Learn more * [How to manipulate HTTP response using Proxyman Map Local Tool](https://proxyman.com/posts/2019-08-03-map-local-feature) * [How to map a Local Response for GraphQL Requests?](https://proxyman.com/posts/2021-01-24-How-To-Map_Response_For_GraphQL_Requests) --- Source: https://proxyman.com/docs/advanced-features/map-local-directory # Map Local (Directory) > Use Proxyman Map Local Directory to serve matching requests from files in a local folder, and fall back to the server when a file is missing. ## 1. What's it? It's a handy tool to map matched requests to local files in a selected directory. If a local file doesn't exist, Proxyman serves the response from the real server. If you would like to map a single local file, check out the Map Local (File) page. - [Map Local (File)](https://proxyman.com/docs/advanced-features/map-local) ## 2. How to use ![Proxyman Map Local editor in Local Directory mode mapping https://httpbin.proxyman.app/anything/* to /Users/Shared/Demo/api](https://proxyman.com/docs/assets/proxyman-map-local-directory-editor.jpg) _Map a URL to a local directory_ ### 2.1 Map a path and its subdirectories `api.proxyman.io/build/v1/*` => All sub-paths after `/v1/` will map to a selected directory. For instance, we select `~/desktop/my_folder` as the local directory. | Real URL | Resolved Local Path | | ------------------------------------------ | -------------------------------- | | http://api.proxyman.io/build/v1/index.html | \~/desktop/my\_folder/index.html | | http://api.proxyman.io/build/v1/js/main.js | \~/desktop/my\_folder/js/main.js | #### How to config | Rule | How to use | Examples | | -------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Wildcard |
  • Check the "Include all subpaths of this URL" checkbox
  • Or use /* at the end of the URL
|
  • api.proxyman.io/build/v1/ (Check ON)
  • api.proxyman.io/build/v1/*
| | Regex |
  • Use (.*) at the end
|
  • https:\/\/api.proxyman.io\/build\/v1\/(.*)
  • https:\/\/api.proxyman.io\/build\/v1\/(.*.css)
| > **Note:** Make sure you use the `()` Regex group operator to tell Proxyman where to map. ### 2.2 Map Entire Host `api.proxyman.io/*` => All sub-paths will map to a selected directory. For instance, we select `~/desktop/my_folder` as the local directory. | Real URL | Resolved Local Path | | ------------------------------------------ | ----------------------------------------- | | http://api.proxyman.io/build/v1/index.html | \~/desktop/my\_folder/build/v1/index.html | | http://api.proxyman.io/build/v1/js/main.js | \~/desktop/my\_folder/build/v1/js/main.js | #### How to config | Rule | How to use | Examples | | -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Wildcard |
  • Leave the path blank
|
  • api.proxyman.io
| | Regex |
  • Use single path that contains (.*) at the end
|
  • https:\/\/api.proxyman.io\/(.*)
  • https:\/\/api.proxyman.io\/(*.html)
| ## 3. Map Local Directory with Scripting Tool ✅ If you would like to do Map Local Directory with **complicated rules,** check out [Scripting](https://proxyman.com/docs/scripting/script#1-whats-it), since it's easier to get the same result. Please check out our [Snippet Code](https://proxyman.com/docs/scripting/snippet-code#2-common-on-request-and-response) to see how to map a local file with JavaScript code. --- Source: https://proxyman.com/docs/advanced-features/map-remote # Map Remote > Use Proxyman Map Remote to redirect matching HTTP, HTTPS, and WebSocket requests to another host, port, or path, such as localhost or staging. ## 1. What's it? Map Remote (**⌥⌘R**) changes the location of an HTTP request to a new destination server, based on your rules. Your client gets the response from the new server as if nothing changed. Map Remote also supports mapping from HTTP to HTTPS and vice versa. ![Proxyman Map Remote window with Localhost to Production, Staging to Production and a Regex rule](https://proxyman.com/docs/assets/proxyman-map-remote-rules.jpg) _Map Remote rules_ > **Note:** Check out common [Map Remote Config](https://proxyman.com/docs/advanced-features/map-remote#7-common-usages) when mapping from HTTP <-> HTTPS. > **Note:** From Proxyman 4.3.0: Map Remote supports Websocket and Secure Websocket. ## 2. Benefits * Use Production endpoints on your Development website for certain endpoints, without changing the source code * Use Development endpoints on your Production website * Send certain request URLs to different destinations * Replace request components, such as Protocol, Host, Port, Path, or Query, on the fly > **Note:** To boost your productivity, you can use the [Scripting feature](https://proxyman.com/docs/scripting/script#1-whats-it) to get the same result as Map Remote by writing simple JavaScript code. > > For instance, [Snippet code to change Production to Localhost server](https://proxyman.com/docs/scripting/snippet-code#change-request-destination-scheme-host-port-path) ## 3. Map Remote with GraphQL Requests From Proxyman 2.27.0+, Map Remote can work with GraphQL requests by a specific QueryName. Please check out the following GraphQL document. - [GraphQL](https://proxyman.com/docs/advanced-features/graphql) ## 4. Using Scripting as Map Remote ✅ If a Map Remote rule is hard to set up, you can do it more easily with the [Scripting Tool](https://proxyman.com/docs/scripting/script#1-whats-it). Please check out [Map Remote Snippet Code](https://proxyman.com/docs/scripting/snippet-code#8-map-remote-with-scripting) to learn how to use Scripting to achieve the same result as Map Remote. For instance, it's easy to do the following with Scripting: * Map v1 to v2 endpoints * Map Production to Localhost * Map Localhost to Production * ... ## 5. Matching Rule > **Note:** Proxyman supports [Regular Expression](https://developer.apple.com/documentation/foundation/nsregularexpression#1965590) and Wildcard from version 2.3.0. Check out [how to use Wildcard and Regex](https://proxyman.com/docs/basic-features/regex). We can define matching rules by using [Wildcard or Regular Expression](https://proxyman.com/docs/basic-features/regex). For matched requests, Proxyman attempts to: * Replace the Protocol, Host, Port, Path, and Query, if they are set * If a component is empty, it won't change that component of the matched request ![Proxyman Map Remote rule editor that maps http://localhost:3000/* to https://httpbin.proxyman.app](https://proxyman.com/docs/assets/proxyman-map-remote-rule-editor.jpg) _Map Remote rule editor_ > **Note:** > > * Leave a text field blank to keep that part unchanged from the matched request > * Wildcards are not allowed in the Map To fields ### Debugging To find which Map Remote rule matches your URL, open the request's Summary tab: 1. Select your request 2. **Summary** tab -> **Debugging Tools** 3. Check the mapped URL ### Preserve Host Header By default, Proxyman overrides the Host header to match the new host in Map Remote. This is needed for most requests to succeed. If you would like to keep the original Host header, check the "Preserve Host Header" checkbox when you create a new entry. Proxyman will keep the Host value. ## 6. How to use * Right-click on the selected request -> **Tools** -> **Map Remote…**. Proxyman fills in the needed data from the selected request. ![Create a Map Remote rule from a request](https://proxyman.com/docs/assets/proxyman-map-remote-context-menu.jpg) _Create a Map Remote rule from a request_ ## 7. Common Usages ### 7.1 Map Localhost (HTTP) to Production (HTTPS) **Result:** | Original URL | To URL | | --------------------------------------------------- | ------------------------------------------------- | | http://localhost:3000 | https://proxyman.io | | http://localhost:3000/pricing | https://proxyman.io/pricing | | http://localhost:3000/v1/user?id=123\&name=proxyman | https://proxyman.io/v1/user?id=123\&name=proxyman | | **POST** http://localhost:3000/login | **POST** https://proxyman.io/login | ### 7.2 Map Production (HTTPS) to localhost (HTTP) | Original URL | To URL | | ------------------------------------------------- | --------------------------------------------------- | | https://proxyman.io | http://localhost:3000 | | https://proxyman.io/v1/user?id=123\&name=proxyman | http://localhost:3000/v1/user?id=123\&name=proxyman | | **POST** https://proxyman.io/login | **POST** http://localhost:3000/login | ### 7.3 Map certain URL to another host * Rule: **https://proxyman.io/v1/user** (for instance) * Select **Any** and **Wildcard** * **Un-Check Include all subpaths of this URL:** Un-check means it doesn't map other subpaths **Map To:** * Protocol: **https** * Host: New Host (e.g. staging.proxyman.io) * Port: **443** (your local port) * Leave Path and Query Empty **Result:** | Original URL | To URL | | ------------------------------------------------- | --------------------------------------------------------- | | https://proxyman.io | https://proxyman.io (does not map the rule) | | https://proxyman.io/v2/setting | https://proxyman.io/v2/setting (does not map the rule) | | https://proxyman.io/v1/user?id=123\&name=proxyman | https://staging.proxyman.io/v1/user?id=123\&name=proxyman | ### 7.4 Map Websocket from localhost to Production | Original URL | To URL | | ----------------------------- | ----------------------------------- | | ws://localhost:4000 | wss://ws.postman-echo.com | | ws://localhost:4000/websocket | wss://ws.postman-echo.com/websocket | ### 7.5 Map Websocket from Production to Localhost | Original URL | To URL | | ----------------------------------- | ----------------------------- | | wss://ws.postman-echo.com | ws://localhost:3000 | | wss://ws.postman-echo.com/websocket | ws://localhost:3000/websocket | ## Learn more * [Switch API endpoint from Production to localhost environment for testing](https://proxyman.com/posts/2025-01-10-switch-api-endpoint-from-localhost-to-production-environment) --- Source: https://proxyman.com/docs/advanced-features/external-proxy # External Proxy > Use Proxyman External Proxy to send HTTP and HTTPS traffic through your company HTTP, HTTPS, SOCKS, or PAC proxy, with bypass rules for some hosts. ## 1. What's it? Some companies have a central proxy server, and all outgoing requests must go through it to reach the Internet. In this case, you may have to set up Proxyman to send all connections to the External Proxy. ## 2. Benefits * Send all traffic to your company's proxy server. * Define hosts or domains that bypass the External Proxy. * Supports HTTP/HTTPS/SOCKS Proxy. * Supports PAC Proxy (Automatic Proxy Configuration) (Proxyman 3.2.0+) ## 3. How to use * **Tools** menu -> **Proxy Settings** -> **External Proxy Settings…** * You can set up an **HTTP, HTTPS, or SOCKS Proxy** that points to your external proxy server. * If you have a **PAC URL**, you can use it in Automatic Proxy Configuration. * Proxyman also supports **Basic Authentication**. * To turn the External Proxy on or off, use **Tools** -> **Proxy Settings** -> **Use External Proxy** (⌥⌘E). ![Proxyman External Proxy settings with HTTP and HTTPS proxy at proxy.example.com:8080, inclusive list and bypass list](https://proxyman.com/docs/assets/proxyman-external-proxy-settings.jpg) _External Proxy settings_ > **Note:** External SOCKS Proxy with authentication is not supported. ## 4. Bypass Proxy * You can define hosts/domains that bypass the external proxy. Separate each host with a comma. Wildcards (\* or ?) are supported. * By default, Proxyman sends all localhost traffic directly, not through the external proxy. This is the **"Always bypass external proxies for localhost"** checkbox, which is on by default. Uncheck it if you want localhost traffic to go through the external proxy too. > **Note:** Localhost traffic is traffic from localhost, 127.0.0.1, or 0.0.0.0 on any port. --- Source: https://proxyman.com/docs/advanced-features/save-session # Save Session > Use Proxyman Save Session to save captured requests, responses, apps, domains, and devices to a file you can reopen later or share with teammates. ## 1. What's it? It's a handy tool to save your entire working session, so you can open it later without losing any debugging information, including: * All Request and Response flows * All Apps and Domains * All Remote Devices ## 2. What's for? * Save the entire session and open it later * Share your debugging session with your QA team or teammates ## 3. How to use? ### 3.1 Save current Session * **File** menu -> **Save Session…**, then select the save location. ![Proxyman File menu with Save Session... highlighted, plus New Session, Open and Open Recent](https://proxyman.com/docs/assets/proxyman-file-menu-save-session.jpg) _File > Save Session_ ### 3.2 Restore previous Session * **File** menu -> **Open…** or **Open Recent** --- Source: https://proxyman.com/docs/advanced-features/protobuf # Protobuf > Decode Protobuf HTTP and HTTPS requests, responses, and WebSocket messages in Proxyman with a .desc file descriptor and a Message Type rule. ## 1. Protobuf * Proxyman macOS can decode the Protobuf body of your HTTP/HTTPS requests and responses with a given Protobuf desc file * Decode Protobuf binary and show it as plain text * Supports a Single Message or multiple Delimited Messages in a single Protobuf binary * Import a desc file and read all its Message Types to decode Protobuf binary * Decode [Protobuf from Websocket](https://proxyman.com/docs/advanced-features/websocket#websocket-with-protobuf-payload) ![Proxyman shows a raw Protobuf request body next to the same body decoded as JSON](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_32_54.png) ## 2. Protobuf File Descriptor (\*.desc) Proxyman requires a File Descriptor (\*.desc) to properly parse the Protobuf Data. There are a few ways to get the File Descriptor: ### 1. Ask your colleagues. If your company uses Protobuf, there's a good chance that your colleagues already have this file, especially the Backend and Frontend teams. It might be one or multiple descriptor files. ### 2. Generate from \*.proto file If you have many \*.proto files, you can generate one \*.desc file with the following command. ```bash # Install protobuf cli if need brew install protobuf # Create `input` folder on the Desktop # Copy all proto files to the `input` folder # Generate 1 descriptor file with multiple proto files protoc --descriptor_set_out=output.desc --include_imports -I=/Users//Desktop/input /Users//Desktop/input/*.proto # Done # output.desc ``` Once you have the Descriptor File, import it to Proxyman: * **Tools** menu -> **Protobuf…** -> click the **Protobuf Schema...** button * Click the **+** button and select the **output.desc** file > **Note:** Proxyman 3.6.0+ only accepts **File Descriptor (\*.desc)** for better Protobuf parsing. > > If you have **\*.proto** files, you can convert them to **\*.desc**. See [Generate from \*.proto file](#2-generate-from-proto-file) above. > **Note:** Proxyman automatically imports all common types from **Google Protobuf**, such as Timestamp, Struct, Value, Enum, Method, etc. > > Proxyman supports both **proto2** and **proto3** syntax. [Read more](https://developers.google.com/protocol-buffers/docs/proto3) ## 3. Protobuf Config Before using Protobuf, you have to set which Message Type Proxyman should use to parse the Protobuf data. The following table describes the settings: | Name | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Schema | Add a `.desc` file if needed | | Message Type | The Class name of the root object in Protobuf binary. **Must include Package name** | | Payload Type: **Auto** | Auto detect if the Protobuf Binary is encoded as a Single Message or [Delimited Message](https://developers.google.com/protocol-buffers/docs/techniques#streaming) | | Payload Type: **Single Message** | Single Message in a Protobuf Binary | | Payload Type: **Delimited List** | Multiple Messages in a Protobuf Binary (Length-Prefix) | ![Proxyman Protobuf Settings rule with matching rule, Add Schema, Message Type and Payload Type options](https://proxyman.com/docs/assets/Screenshot%202026-01-31%20at%2010.04.50.png) _Decode Protobuf HTTPS Response with Proxyman_ ## 4. How to use? There are **two** ways to parse Protobuf properly with named fields: * Define Protobuf Rules * Read from Content-Type Header ### 4.1 Define Protobuf Rule 1. Your Protobuf request should have a Content-Type header: `Content-Type: application/x-protobuf` or `Content-Type: application/protobuf` 2. Proxyman detects the Protobuf payload and shows a warning that it can't parse it properly because the message type is missing. Click **Add** to open Protobuf Settings. Alternatively, you can right-click on your request -> **Tools** -> **Protobuf…** ![Proxyman Protobuf request body with a Missing Message Type warning, an Add button and numbered fields without names](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_56_19.png) 3\. In the Protobuf rule window, select the Message Type for this Request/Response (add a desc file if needed). > **Note:** If the Request and Response use different Protobuf Message Types, select the \`Use different Message Type for Request / Response\` checkbox. 4\. Click **Add** and see the body in JSON format. ### 4.2 Read from Content-Type Header You can **dynamically** provide the Protobuf Config from `Content-Type` For example: Your `Content-Type` in the Request or Response might look like: `Content-Type: application/x-protobuf; messageType="tutorial.Address"; delimited=true` `Content-Type: application/x-protobuf; messageType="com.proxyman.User"; delimited=false` This tells Proxyman the Message Type and the payload encoding of the Protobuf body. ## 5. ✅ Protobuf With Websocket (from macOS 6.5.0 or later) * Decode a single binary WebSocket frame: Read [websocket.md](https://proxyman.com/docs/advanced-features/websocket) * You can create a Protobuf rule for WebSocket. Use the Request Message Type for client messages, and the Response Message Type for server messages. ## 6. Troubleshooting ### 6.1 Some name fields are missing Some field names can be missing when their definitions are not in your Protobuf File Descriptor. Your descriptor might be out of date. **Solution**: * Remove the old Protobuf Schema and add the latest descriptor file from your server. * If you're using Proxyman 3.5.2 or older, please update to Proxyman 3.6.0 or later. Then, use File Descriptor (\*.desc) for better results. ## Learn more * [How to capture WebSocket and decode Protobuf message](https://proxyman.com/posts/how-to-capture-websocket-with-protobuf-message) * [Proxyman vs mitmproxy: Decode Protobuf WebSocket Messages](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Protobuf-WebSocket) --- Source: https://proxyman.com/docs/advanced-features/websocket # WebSocket > Capture and decrypt WebSocket (WS/WSS) traffic with Proxyman from web browsers, iOS devices and simulators, Android, and NodeJS or Python servers. ## 1. What's it? Proxyman can capture WebSocket (WS) and Secure WebSocket (WSS) traffic and lets you preview it easily. * Capture WS/WSS from iOS Physical devices and iOS Simulator (Required [Atlantis framework](https://github.com/ProxymanApp/atlantis)) * Capture WS/WSS from Web Browser and Mac applications. * Capture WS/WSS from Android Physical devices or Android Emulators. * Pretty-print WebSocket messages. * Filter All / Sent / Received messages. * See the content in JSON / Tree Preview / HEX format. * Customize Columns: Frame, Length, Data, Time, ... * Auto-decode binary messages to JSON if possible. * Open WebSocket messages in external editors, such as Sublime or VS Code. * Edit, drop, or send WebSocket messages with [Scripting](#7-modify-websocket-messages-with-scripting) (macOS Proxyman 26.2.0 or later, Windows/Linux Proxyman 26.1.0 or later). ## 2. Capture WS/WSS from Web Browsers ### Localhost websocket Proxyman can capture a localhost WebSocket, such as ws://localhost:3000, from Google Chrome with [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup). 1. Go to the **Setup** menu -> **Automatic Setup…** 2. Select Google Chrome (New Profile or Current Profile). A new Google Chrome window opens. 3. Open your localhost WebSocket page in this window. Proxyman will capture it. ### Production websocket Proxyman automatically captures your WS/WSS traffic from Google Chrome, without any setup. 1. Open Proxyman and Google Chrome 2. Make some WS/WSS traffic, for example on [https://echo.websocket.org/.ws](https://echo.websocket.org/.ws) 3. Inspect the WS/WSS data in Proxyman ### Websocket with Protobuf Payload From Proxyman macOS 6.5.0 or later, Proxyman can decode Protobuf in your WebSocket messages. 1. Make sure Proxyman can capture your WebSocket traffic first 2. Right-click on a WebSocket Protobuf message -> **Protobuf** -> **Decode Raw Text…** or **Decode with Message Type…** * **Raw mode**: Useful if you don't have a Protobuf desc file. * **Message Type**: Use a Message Type from your Protobuf desc file. ![Proxyman context menu on a binary WebSocket message with Protobuf, Decode Raw Text and Decode with Message Type](https://proxyman.com/docs/assets/Screenshot%202026-01-30%20at%2015.11.30.jpg) _Decode WebSocket payload with Protobuf_ ## 3. Capture WS/WSS from iOS If your iOS app uses **URLSessionWebSocketTask** or iOS WebSocket libraries, such as Starscream or SocketRocket, Proxyman might not be able to capture WS/WSS traffic. * **Reason**: This is by Apple's design. **URLSessionWebSocketTask** doesn't respect the System HTTP Proxy. All WS/WSS traffic goes directly to the Internet, so Proxyman or Charles Proxy can't capture it. * Example App: [https://github.com/ProxymanApp/websocket-example-ios-app](https://github.com/ProxymanApp/websocket-example-ios-app) ### ✅ Solution 1 (Recommended for iOS 17 or later) 1. Follow the setup guide for your [iOS Devices](https://proxyman.com/docs/debug-devices/ios-device) or [iOS Simulators](https://proxyman.com/docs/debug-devices/ios-simulator). Make sure the certificate is installed and trusted on your device. 2. In Proxyman: **Tools** -> **Proxy Settings** -> **SOCKS Proxy Settings…** -> enable it. Take note of the port. 3. In the main Proxyman window, take note of the current IP in the toolbar. ![Proxyman status popover with IP 192.168.64.4, Proxy Port 9090, and Recording, macOS proxy and Network Extension toggles](https://proxyman.com/docs/assets/proxyman-status-popover.jpg) _Get Proxyman current IP_ 4. In your app: Configure a SOCKS proxy. Make sure it's only on for debug builds, for example with a switch. You don't want this setting in your release build. * For NWConnection ```swift let parameters = webSocketURL.scheme == "wss" ? NWParameters.tls : NWParameters.tcp let options = NWProtocolWebSocket.Options() options.autoReplyPing = true parameters.defaultProtocolStack.applicationProtocols.insert(options, at: 0) if #available(iOS 17.0, *) { let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) // Please replace x.x.x.x with a real Proxyman IP let config = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy) let context = NWParameters.PrivacyContext(description: "my socksv5Proxy") context.proxyConfigurations = [config] parameters.setPrivacyContext(context) } let connection = NWConnection(to: .url(webSocketURL), using: parameters) connection.start(queue: .main) ``` * For URLSession and URLSessionWebSocketTask ```swift private lazy var urlSession: URLSession = { let config = URLSessionConfiguration.default if #available(iOS 17.0, *) { let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) // Please replace x.x.x.x with a real Proxyman IP let proxyConfig = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy) config.proxyConfigurations = [proxyConfig] } return URLSession(configuration: config, delegate: nil, delegateQueue: nil) }() ``` 5. Done ✅ ![Proxyman capturing wss://echo.websocket.org messages from a URLSessionWebSocketTask app in the iOS Simulator](https://proxyman.com/docs/assets/Screenshot%202024-11-29%20at%201.17.23%E2%80%AFPM.jpg) _Capture WebSocket from iOS with Proxyman_ * Credit to [**FranklinSamboni**](https://github.com/FranklinSamboni) **->** [https://github.com/ProxymanApp/Proxyman/issues/586#issuecomment-2125082129](https://github.com/ProxymanApp/Proxyman/issues/586#issuecomment-2125082129) * Tutorial: [How to intercept and debug WebSocket from iOS simulators or devices](https://proxyman.com/posts/2019-10-18-WebSocket-Debugging) ### ✅ Solution 2 Use [Atlantis Framework](https://github.com/ProxymanApp/atlantis#features) (developed by Proxyman) to capture WS/WSS **URLSessionWebSocketTask** traffic from iOS. Read more in the [Atlantis WS/WSS traffic guide](https://github.com/ProxymanApp/atlantis#wswss-traffic). ## 4. Capture WebSockets from your Web Browser (Chrome, Safari, etc) * Proxyman can capture WS/WSS from a web browser out of the box. No need to configure anything. * How to use: Open Google Chrome -> Visit your website that makes a WS/WSS connection -> Open Proxyman -> Find your WebSocket domains -> On the Response panel, click **Enable SSL Proxying** for these domains. Reload your website in the browser. Proxyman will capture and decrypt WS/WSS ✅ ## 5. Capture Websocket from NodeJS, Golang, Python Server * Proxyman can capture WS/WSS from your NodeJS, Golang, Python, and Ruby server. * How to use: Read [automatic-setup.md](https://proxyman.com/docs/automatic-setup/automatic-setup) to start your server in the Terminal it opens -> Make a WS/WSS connection -> Proxyman automatically captures and decrypts it ✅ ## 6. Map Websocket from Localhost <-> Production You can map WebSocket traffic from localhost <-> Production. Please check out the [Map Remote Tool](https://proxyman.com/docs/advanced-features/map-remote#74-map-websocket-from-localhost-to-production). ## 7. Modify WebSocket Messages with Scripting From Proxyman 26.2.0 for macOS and Proxyman 26.1.0 for Windows/Linux, you can change WebSocket messages on the fly with a few lines of JavaScript. Check **Modify WebSocket Messages** on a Scripting rule, then use `onWebsocket()` to: * Edit a text or binary message, in both directions. * Drop a message, so the other side never sees it. * Send a new message to the client or the server. * Close the WebSocket to test how your app reconnects. ```javascript function onWebsocket(context, url, request, response, message) { if (message.from === "server" && message.type === "text") { message.data = message.data.replace("staging.example.com", "api.example.com"); } return message; } ``` - [Modify WebSocket Messages](https://proxyman.com/docs/scripting/modify-websocket-messages) ## Learn more * [How to modify WebSocket messages with Scripting](https://proxyman.com/posts/2026-10-23-modify-websocket-messages-with-scripting) * [How to capture WebSocket and decode Protobuf message](https://proxyman.com/posts/how-to-capture-websocket-with-protobuf-message) * [Proxyman vs mitmproxy: Decode Protobuf WebSocket Messages](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Protobuf-WebSocket) --- Source: https://proxyman.com/docs/advanced-features/clear-session # Clear Session > Use Proxyman Clear Session to remove all captured requests, domains, and clients from the current session and free memory without quitting the app. Clear the current working session, including all Requests, Domains, and Clients. ## What's for? * Start a fresh session without quitting the app * Release unneeded memory ## How to use * **Flow** menu -> **Clear Session** (⌥⇧⌘⌫) ![Proxyman Flow menu with Clear Session (⌥⇧⌘⌫) highlighted](https://proxyman.com/docs/assets/proxyman-flow-menu-clear-session.jpg) _Clear Session in the Flow menu_ --- Source: https://proxyman.com/docs/advanced-features/blacklist # Block List > Use the Proxyman Block List to block or hide requests by domain, wildcard, regex, or app, so ads, analytics, and noisy pings stay out of your session. ## 1. What's it? The Block List Tool is useful when you would like to **block or hide** certain domains during a debugging session. For instance, you can use Block List in the following situations: * Block all ad requests from particular domains * Block all analytics requests that flood your workspace * Block all annoying ping requests from your app, so fewer requests show in Proxyman * Hide analytics traffic from your website without blocking it For all blocked domains in the Block List, Proxyman **drops the connection.** ![Proxyman Block List window with rules that block a wildcard domain, Google Chrome and WhatsApp](https://proxyman.com/docs/assets/Screenshot%202025-09-05%20at%2021.11.17.png) _Block certain requests by domain or client_ ## 2. Block Actions Block List supports a few block actions to suit your needs:
Block ActionDescription
Block & Hide RequestMatched requests are blocked and don't show in the app.
Block & Display RequestsMatched requests are blocked, but the blocked requests still show in the app.
Hide, but not BlockOnly hides the matched requests without blocking them. Useful when you want to hide annoying requests but not block them.
![Proxyman Block List rule editor with the Action menu: Block & Hide, Block & Display, and Hide, but not Block](https://proxyman.com/docs/assets/proxyman-block-list-rule-editor.jpg) _Choose a block action_ ## 3. How to use it? * **Tools** Menu -> **Block List** * Right-click on the requests or domains -> **Tools** -> **Block List...** > **Tip:** **⌥⌘\[** to quickly open the Block List window ## 4. Block all traffic from a given App * On Proxyman macOS 5.24.0 or later, you can select an app and block all of its traffic. In the rule editor, click **Select App…** next to **Block App**. ![Proxyman Block List rule editor with Block App set to Dropbox and the Block and Hide Request action](https://proxyman.com/docs/assets/Screenshot%202025-09-02%20at%2010.08.23.jpg) _Block all traffic from an app_ --- Source: https://proxyman.com/docs/advanced-features/whitelist # Allow List > Use the Proxyman Allow List to capture only the domains you choose and let all other traffic bypass Proxyman, so you can focus on your own APIs. ## 1. What's it? The Allow List tool lets you define which domains are **allowed to appear** in the Proxyman app. Requests that don't match a rule don't go through Proxyman (they bypass it). It's useful in the following situations: * Ignore all domains except the ones you are debugging (e.g. producthunt.com) * Reduce the number of unnecessary requests and focus on the domains you need to track If you would like to block certain domains, use the [Block List](https://proxyman.com/docs/advanced-features/blacklist) instead. ## 2. How to use? * **Tools** menu -> **Allow List…** * Right-click on the selected request -> **Tools** -> **Allow List…** ![Right-click > Tools > Allow List](https://proxyman.com/docs/assets/proxyman-allow-list-context-menu.jpg) _Right-click > Tools > Allow List_ ![Proxyman Allow List window with an Only httpbin rule matching https://httpbin.proxyman.app/*](https://proxyman.com/docs/assets/proxyman-allow-list-window.jpg) _Allow List window_ > **Tip:** Press **⌥⌘]** to quickly open the Allow List window. --- Source: https://proxyman.com/docs/advanced-features/charles-proxy-converter # Charles Proxy Converter > Convert Charles Proxy .chls session files to HAR and open them in Proxyman, so you can keep working with traffic you captured in Charles. ## 1. What's it? Proxyman can convert `chls` files from the Charles Proxy app to the `har` format, which Proxyman can read. > **Tip:** Charles Proxy must be installed on your Mac to convert `chls` files. You can also convert files manually from the **File** menu -> **Convert** -> **From .chls to .har**. ![Proxyman Converter sheet with the Charles Proxy app path, a From .chls File field and the To .har File output](https://proxyman.com/docs/assets/proxyman-charles-chls-to-har-converter.jpg) _Convert .chls to .har_ ## 2. How does it work? Proxyman uses the [Charles Proxy command-line convert tool](https://www.charlesproxy.com/documentation/tools/command-line-tools/) to convert `.chls` files to `.har` files, which Proxyman can read. 1. When you open a `chls` file, Proxyman looks for the Charles Proxy app by its bundle ID: `com.xk72.Charles` 2. Proxyman converts the file with the `convert` command: ``` $ /Applications/Charles.app/Contents/MacOS/Charles convert ~/Desktop/input.chls ~/Desktop/output.har ``` 3\. The output is a `har` file. In this example, it's saved to your Desktop folder. ## 3. How to use? There are several ways to open `chls` files: * Open the `chls` file directly (double-click the file, or use **Open With** in Finder) * Drag and drop the file into the Proxyman app * **File** -> **Open…** and select the `chls` file ## Learn more * [Migrate from Charles to Proxyman](https://proxyman.com/posts/2020-07-03-Migrate_From_Charles_To_Proxyman) --- Source: https://proxyman.com/docs/advanced-features/custom-certificates # Custom Certificates > Add custom root, server, and client certificates to Proxyman for SSL pinning and mutual TLS, and generate a self-signed root certificate Apple trusts. ## 1. What's it? Proxyman supports custom **Root Certificates**, **Server Certificates**, and **Client Certificates**. You can add your own certificates, and Proxyman uses them to set up the SSL connection between your clients, your servers, and the Proxyman app. | Custom Certificate Type | Purpose | How Proxyman uses | | ----------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | **Server Certificate** | For intercepting HTTPS Traffic from clients that use SSL-Pinning | Use this certificate for SSL-Handshake to your Clients | | **Client Certificate** | For intercepting HTTPS Traffic from clients that use Mutual Authentication | Use this certificate for SSL-Handshake to specific Server | | **Root Certificate** | For intercepting HTTPS Traffic from clients and servers without using local Proxyman certificates | SSL Handshake for both clients & servers | ![Proxyman Custom Certificates window on the Root Certificate tab with the Proxyman CA certificate Installed & Trusted](https://proxyman.com/docs/assets/proxyman-custom-root-certificate.jpg) _Root Certificate tab_ > **Note:** The Proxyman Root Certificate is generated locally on your Mac. You can also generate your own root certificate and add it to Proxyman. See [how to generate a self-signed root certificate](https://proxyman.com/docs/advanced-features/custom-certificates#6-how-to-generate-self-signed-certificates-for-custom-root-certificate-that-comply-with-new-apples-security-requirements). ## 2. Certificate Formats Proxyman accepts the following formats: | Custom Certificate | PEM or DER | PKCS #12 (p12) | | ------------------ | ------------- | -------------- | | Root Certificate | Not Supported | Supported | | Client Certificate | Supported | Supported | | Server Certificate | Supported | Supported | * PKCS #12 (p12). * PEM or DER Private Key and Certificate file. > **Note:** > > - Proxyman automatically detects the format of the Private Key and Certificate file (PEM or DER). > - Proxyman asks for the password when you import an encrypted Private Key or PKCS #12 file. > - All passphrases are securely stored in Proxyman Keychain. > **Note:** If your certificates are in a format that Proxyman doesn't support, convert them to p12 or PEM/DER before importing. ## 3. Certificate Requirement on macOS 10.15+ and iOS 13+ If you use a custom Root Certificate or Server Certificate on macOS 10.15 or later, or iOS 13 or later, the SSL handshake can fail in Safari or on iOS devices unless the certificate meets these requirements: * RSA keys must use a key size of 2048 bits or more * The hash algorithm must be in the SHA-2 family * The DNS name of the server must be in the Subject Alternative Name (SAN). The Common Name (CN) is no longer trusted * The certificate must be valid (today is between the Not Before and Not After dates) * TLS server certificates must contain an ExtendedKeyUsage (EKU) extension containing the **id-kp-serverAuth** OID. Read more: [Requirements for trusted certificates in iOS 13 and macOS 10.15](https://support.apple.com/en-us/HT210176) > **Note:** If this is too complicated, let Proxyman do it for you. Open the **Certificate** menu -> **Install Certificate on this Mac…** -> select the **Automatic** tab. ## 4. Common issues | Problem | Solution | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Private Key and Certificate are not matched | Try different certificates and private keys and make sure they match | | Get SSL Handshake Error for custom certificates |
  • Try to add the custom Certificate to System Keychain and Trust it
  • Certificate doesn't match the requirement from macOS => Read [section 3](https://proxyman.com/docs/advanced-features/custom-certificates#3-certificate-requirement-on-macos-1015-and-ios-13)
  • Check the expiry date of the Certificate
| | Could not import certificate due to invalid passphrase | Ask your team lead for the correct passphrase to open the encrypted Private Key or P12 file | ## 5. How to use * Open the **Certificate** menu -> **Add Custom Certificates…** ## 6. How to generate self-signed certificates for Custom Root Certificate that comply with new Apple's Security Requirements Because of [Apple's requirements from iOS 13 and macOS Catalina (10.15)](https://proxyman.com/docs/advanced-features/custom-certificates#3-certificate-requirement-on-macos-1015-and-ios-13), you need some extra configuration to generate a self-signed certificate that works. Follow these steps: 1. Create a `cert.config` file in your **Desktop** folder ``` [ ca ] default_ca = CA_default [ CA_default ] default_md = sha256 [ v3_ca ] subjectKeyIdentifier=hash authorityKeyIdentifier=keyid:always,issuer basicConstraints = critical,CA:true keyUsage=critical,keyCertSign extendedKeyUsage = serverAuth,clientAuth [ req ] prompt = no distinguished_name = req_distinguished_name [ req_distinguished_name ] C=US L=US O=Proxyman LLC CN=proxyman.dev OU=Proxyman ``` * Update the values of the C, L, O, CN, and OU parameters. 2\. Generate an RSA key in the Terminal app. (Replace **your\_password** with any password, e.g. 123456) ```bash cd ~/Desktop openssl genrsa -aes256 -passout pass:your_password -out key.pem 2048 ``` 3\. Generate the self-signed certificate and private key. (Replace **your\_password** with the password in step 2) ``` openssl req -x509 -new -nodes -passin pass:your_password -config cert.config -key key.pem -sha256 -extensions v3_ca -days 825 -out root-ca.pem ``` 4\. Convert to p12 format. (Replace **your\_password** with the password in step 2) ``` openssl pkcs12 -export -legacy -out root-ca.p12 -in root-ca.pem -inkey key.pem -passin pass:your_password -passout pass:your_password ``` 5\. You now have a **root-ca.p12** file. Move on to the next step. > **Note:** If you can't import your custom certificate on macOS 14 (OpenSSL v3) or later, use the \`-legacy\` flag in step 4. > > Reference: [MAC verification failed during PKCS12 import (Stack Overflow)](https://stackoverflow.com/questions/70431528/mac-verification-failed-during-pkcs12-import-wrong-password-azure-devops) ## 7. Import as a Custom Root Certificate 1. Open the **Certificate** menu -> **Add Custom Certificates…** -> select the **Root Certificate** tab 2. Click the **Import** button -> **Import P12...** 3. Select the **root-ca.p12** file and enter the password. 4. Trust your custom certificate in the Keychain Access app: * Open the Keychain Access app * Search for the certificate you've added. The name might be the common name (CN) of the certificate * Double-click it to open it, then select **Always Trust** * Close the window to save the change ![macOS Keychain Access certificate window with Trust set to Always Trust](https://proxyman.com/docs/assets/Screen%20Shot%202020-09-09%20at%2006.30.51.png) 5\. Check that you see the green check mark, which means the certificate is installed and trusted. ## 8. Import as a Server/Client Certificate For custom Server or Client certificates, don't generate a self-signed certificate. Ask your teammate or team lead for the certificate your company uses. It can be in DER/PEM or P12 format. Then import it in the **Server Certificates** or **Client Certificates** tab of the Custom Certificates window. ![Proxyman Certificate Importer sheet with a PEM certificate file and a private key file selected](https://proxyman.com/docs/assets/Screen%20Shot%202020-06-26%20at%2010.54.35.png) > **Note:** You don't need to trust the certificate in the System Keychain because it's not a Root Certificate. ## Learn more * [How to generate and use Custom Root Certificates on Proxyman](https://proxyman.com/posts/2020-09-09-Generate-Self-Signed-Certificate-iOS13-Mac-Catalina) --- Source: https://proxyman.com/docs/advanced-features/graphql # GraphQL > Debug GraphQL requests in Proxyman: match rules by query name, prettify queries, show a Query Name column, and mock responses with scripts. ## 1. Use Debugging Tools with GraphQL Requests From Proxyman 2.27.0, you can use debugging tools with GraphQL requests by specifying the GraphQL Query Name. Matching by GraphQL QueryName works with Breakpoint, Map Local, Map Remote, Block List, Allow List, and the Scripting Tool. ### How to use 1. Open the debugging tool (e.g. Breakpoint) 2. Create a new rule 3. Click the **Use Wildcard** dropdown -> **Advanced** -> check **GraphQL QueryName** 4. Enter the GraphQL QueryName The debugging tool first matches the original matching rule, then matches the GraphQL QueryName. ![Proxyman Breakpoint rule editor with Use Wildcard > Advanced > GraphQL QueryName checked](https://proxyman.com/docs/assets/Screen_Shot_2021-05-26_at_15_46_13.png) > **Note:** From build 3.0.0, Proxyman automatically fills in the GraphQL Query Name when you create a debugging tool rule. ## 2. GraphQL Prettier From Proxyman 2.33.0, Proxyman can prettify (beautify) the GraphQL query. To turn it on, open the **Tools** menu -> **Custom Previewer Tab…** -> check the **GraphQL** checkbox. ![Proxyman GraphQL tab in the Request panel with a prettified GetUser query and its GraphQL variables](https://proxyman.com/docs/assets/proxyman-graphql-query-prettier.jpg) _Prettified GraphQL query_ ## 3. Show GraphQL Query Name on the main table view Proxyman can extract and show the Query Name of each GraphQL request. Right-click on the column header and enable the **Query Name** column. ![Proxyman main table with a Query Name column showing GetUser, ListPosts and CreatePost, next to a Comment column](https://proxyman.com/docs/assets/proxyman-graphql-query-name-column.jpg) _Query Name column_ - [Custom Header Column](https://proxyman.com/docs/basic-features/custom-header-column) ## 4. Debug GraphQL Requests (Legacy - Proxyman 2.26.0 and below) GraphQL uses the same URL for different queries, so URL-based debugging tools (e.g. Map Local, Breakpoint, Map Remote) don't work well with it. However, with the Scripting Tool, you can: * Map a local response based on the QueryName * Change the query, body, and headers of GraphQL requests and responses ### Map Local with the Scripting Tool You can use the Scripting Tool to map a local file as the response: 1. Open Proxyman 2. Enable SSL Proxying on the GraphQL domain 3. Make sure you can see HTTPS requests from your domain 4. Right-click on the request -> **Tools** -> **Scripting…** to create a script for its URL 5. To import a local file: click the **More** button -> **Import JSON or Other File...** -> select your file 6. The following script sets a local file as the response of a GraphQL request with QueryName="user" ```javascript // Import file from More Button -> Import JSON or Other files const file = require("@users/B02D96D5.default_message_32E64A5B.json"); function onRequest(context, url, request) { // 1. Extract the queryName from the request var queryName = request.body.query.match(/\S+/gi)[1].split('(').shift(); // Or extract the operationName var operationName = request.body.operationName // 2. Save to sharedState sharedState.queryName = queryName sharedState.operationName = operationName // Done return request; } function onResponse(context, url, request, response) { // 3. Check if it's the request we need to map if (sharedState.queryName == "user") { // 4. Import the local file by Action Button -> Import // Get the local JSON file and set it as a body (like Map Local) response.headers["Content-Type"] = "application/json"; response.body = file; } // Done return response; } ``` ### Manipulate Headers, Query, Body 1. Use the same code and change the queryName 2. Use the [snippet code](https://proxyman.com/docs/scripting/snippet-code#2-common-on-request-and-response) to change the values ## Learn more * [How to map a local response for GraphQL requests](https://proxyman.com/posts/2021-01-24-How-To-Map_Response_For_GraphQL_Requests) * [Display Query Name from GraphQL requests](https://proxyman.com/posts/2021-03-28-Display-QueryName-From_GraphQL-Request) * [Manipulate GraphQL requests with the Breakpoint tool](https://proxyman.com/posts/2023-03-16-GraphQL-Request-With-Breakpoint) --- Source: https://proxyman.com/docs/advanced-features/network-throttling # Network Conditions > Use Proxyman Network Conditions to simulate slow or lossy networks like 3G, 4G, or poor Wi-Fi for one host or all traffic, and test your app. ## 1. What's it? Network Conditions (Network Throttling) lets developers simulate poor network environments. Proxyman provides various preset profiles: | Profile | Description | | -------------------- | ---------------------------------------- | | 100% Loss | 100% of packets are dropped | | Very Bad Network | Download/Upload: < 1mbps | | Slow Network | Download/Upload: 5-10 mbps | | Medium Network | Download/Upload: 10-20 mbps | | 2G (EDGE) | Download: <240kbps, Upload <200kbps | | 3G | Download: <780kbps, Upload <330kbps | | 4G (LTE) | Download: 30-50mbps, Upload 5-10mbps | | 5G | Download: 50-150mbps, Upload 10-50mbps | | Wi-Fi | Download: 25-40mbps, Upload 15-30mbps | | Wi-Fi 802.11ac | Download: 150-250mbps, Upload 70-100mbps | ## 2. Benefit? * Various preset profiles: 3G, 4G, 5G, Wi-Fi, Bad/Medium Network, etc. * Simulate different network conditions (download/upload bandwidth, packet drop rate, delay). * Easily test your app under a particular network condition. * Apply to all traffic that goes through Proxyman (**Apply System-wide**) or only to **certain hosts**. > **Note:** From Proxyman 6.9.0, you can create your own profile. In the rule editor, click **Custom Profile...** next to the Network Profile dropdown, then set the download and upload bandwidth (Mbps), delay (ms), and packet loss (%). Proxyman saves your custom profiles so you can reuse them. > **Note:** To better simulate real life, the download/upload bandwidth is not fixed. It changes randomly within the given range. ## 3. How to use it? Open the **Tools** menu -> **Network Conditions…** (⌥⌘J), or right-click a request -> **Tools** -> **Network Conditions…** ![Proxyman Network Conditions rule Simulate 3G with the 3G profile, bandwidth, packet loss, delay and Custom Profile... button](https://proxyman.com/docs/assets/proxyman-network-conditions-rule-editor.jpg) _Simulate a 3G network_ ## 4. Alternative * Network Link Conditioner for macOS: [Network Link Conditioner guide on NSHipster](https://nshipster.com/network-link-conditioner/) ## Learn more * [Simulate poor network conditions on iOS with Proxyman](https://proxyman.com/posts/2022-06-25-Simulate-slow-network-with-Proxyman-network-conditions-tool) --- Source: https://proxyman.com/docs/advanced-features/multiple-filters # Multiple Filters > Combine up to 10 Proxyman filters with AND or OR to find requests by URL, host, header, body, status code, method, client, comment, and more. ## 1. What's it? From build 2.22.0+, you can combine many filters at one time. * Filter requests and responses with complex criteria, quickly and easily * Proxyman remembers your last filter settings * Handy shortcuts * Many filter types: URL, Host, Query String, Request Header, Response Header, Request Body, Response Body, Status Code, Method, Client, IP Address, GraphQL, Color, Comment, Duration, and Body Size * Combine all filters with AND / OR ![Proxyman filter bar with URL contains httpbin.proxyman.app AND Method equal POST, showing only POST requests](https://proxyman.com/docs/assets/proxyman-multiple-filters.jpg) _Combine two filters with AND_ ## 2. Shortcut | Shortcut | Description | | -------- | -------------------------------------------- | | ⌘F | Show the filter and focus on the last one | | ⌘N | Clone a new filter | | ⇧⌘N | Remove the current filter | | ⌘↑ | Focus on the previous filter | | ⌘↓ | Focus on the next filter | | ESC | Hide the filter | > **Note:** You can add up to 10 filters. > > The free version allows only 1 filter. ## Learn more * [Multiple Filters: a useful tip to boost your productivity](https://proxyman.com/posts/2021-04-08-Use_Multiple_Filters) --- Source: https://proxyman.com/docs/advanced-features/custom-filters # Custom Filters > Save your current Proxyman filters as a custom filter button on the filter bar, then reuse, override, rename, or delete it with one click. ## 1. What's it? From Proxyman 4.11.0 or later, you can save your current filter settings as a custom filter and use it again later. * Create a custom filter button on the filter bar from your current filter settings * Manage the filter buttons: create, override, delete, and rename * Save time ✅ ## 2. How to use ### Create new filter 1. Set up your filter (single or [multiple filters](https://proxyman.com/docs/advanced-features/multiple-filters)) 2. Click the **Save** button -> **New Filter…** -> enter a name 3. The new filter is added to the filter bar. ![Proxyman filter bar with a saved httpbin POST custom filter, URL and Method filters, and the Save button](https://proxyman.com/docs/assets/proxyman-custom-filter-save-button.jpg) _Create new custom filter_ ### Override 1. Change your filter settings 2. Click the **Save** button -> **Override** -> select the filter you want to override ![Proxyman Save menu with the Override submenu listing a saved custom filter](https://proxyman.com/docs/assets/2.jpg) _Override an existing filter_ ### Delete or Rename 1. Right-click on the filter button 2. Select **Delete** or **Rename…** ![Right-click menu on the httpbin POST custom filter in Proxyman with Delete and Rename... options](https://proxyman.com/docs/assets/proxyman-custom-filter-rename-delete.jpg) _Delete or rename a custom filter_ --- Source: https://proxyman.com/docs/advanced-features/publish-to-gist # Publish to Gist > Publish selected Proxyman requests and responses to a public or private GitHub Gist, so you can share them with your team using one link. ## 1. What's it? From Proxyman 2.28.0+, you can publish request and response data to GitHub Gist. * Proxyman needs the "Read/Write Gist" permission to publish a Gist on your behalf. * The first time, Proxyman opens the GitHub authorization page. ## 2. Benefit * **Instantly** create a Gist from the selected requests and responses, and **quickly** share it with your colleagues. * Supports Private and Public Gists. * Only requires the **"Read/Write Gist"** permission. It doesn't ask for your email, username, or other permissions. * The GitHub access token is stored securely in the Keychain. Here is what a published Gist looks like: [example Proxyman Gist](https://gist.github.com/NghiaTranUIT/e116a60e286c917a5cbfd61aff32194c) To choose between a private and a public Gist, open **Proxyman** -> **Settings** -> **GitHub**. ![Proxyman Settings GitHub tab with the Authorize button and options to publish a Private or Public Gist](https://proxyman.com/docs/assets/proxyman-settings-github-gist.jpg) _GitHub Gist settings_ ## 3. How to use 1. Select your requests on the main table view 2. Right-click to open the context menu -> **Export** -> **Publish to Gist…** ![Export > Publish to Gist](https://proxyman.com/docs/assets/proxyman-publish-to-gist-menu.jpg) _Export > Publish to Gist_ --- Source: https://proxyman.com/docs/advanced-features/reverse-proxy # Reverse Proxy > Use Proxyman Reverse Proxy to capture HTTP and HTTPS traffic from apps and command-line tools that ignore the system proxy, via a local port. ## 1. What's it? Reverse Proxy creates a **local web server** that transparently forwards your traffic to a remote server. This way, Proxyman can capture and log your traffic. Reverse Proxy is useful when you are working on a client that doesn't support an HTTP/HTTPS proxy, or when the HTTP proxy config is too complicated. For instance, most command-line apps don't respect the system HTTP/HTTPS proxy, so Proxyman can't capture their traffic. To fix it, you can either: * Explicitly configure an HTTP/HTTPS proxy. It can be complicated and depends on the network library you are using. Read [I couldn't see any requests from 3rd-party network libraries](https://proxyman.com/docs/troubleshooting/couldnt-see-any-requests-from-3rd-party-network-libraries) to learn more. * Use Reverse Proxy. Reverse Proxy is available on Proxyman 2.29.0+. ## 2. Benefit * Connect your client to the Proxyman local web server, and Proxyman forwards your traffic to the remote host. No need to set up an HTTP/HTTPS proxy on your client. * Import Reverse Proxy settings from Charles Proxy. * Preserve the Host header. * Proxyman automatically selects an available port when you create a new entry. * Use Breakpoint, Map Local, and Scripting with Reverse Proxy traffic 💯. ## 3. How to use 1. Open the **Tools** menu -> **Reverse Proxy…** 2. Create a new entry and enter a Remote Host and Remote Port. Proxyman selects the Local Port automatically. You can change it to a different port, but it must be available. 3. Save. 4. In your client app, change the URL to `http://localhost:` (e.g. `http://localhost:10000`) 5. Make a request and inspect the traffic in the Proxyman app. ![Proxyman Reverse Proxy window with an httpbin entry that maps local port 10000 to httpbin.proxyman.app on port 443](https://proxyman.com/docs/assets/proxyman-reverse-proxy-window.jpg) _Reverse Proxy window_ ![Proxyman Reverse Proxy entry editor with local port 10000, remote host httpbin.proxyman.app and remote port 443](https://proxyman.com/docs/assets/proxyman-reverse-proxy-entry-editor.jpg) _Reverse Proxy entry_ > **Note:** Proxyman performs the SSL handshake with your remote server if the Remote Port is 443. Otherwise, it treats the remote server as a plain HTTP web server. > > From Proxyman 5.17.0, check **Force Using SSL when connecting to Remote Port** to use SSL/TLS with any remote port. > **Note:** **Preserve Host in Header fields** keeps the original Host value. Use it with caution, because your remote server can reject the request if the Host value doesn't match. ## Learn more * [How to use Reverse Proxy to capture HTTP/HTTPS from apps that don't use an HTTP proxy](https://proxyman.com/posts/2023-03-22-How-to-use-Reverse-Proxy) --- Source: https://proxyman.com/docs/advanced-features/code-generator # Code Generator > Turn captured requests into cURL, Swift, Python, Go, Kotlin, JavaScript, and other code snippets with the Proxyman Code Generator tab. ## 1. What's it? Code Generator turns your captured HTTP/HTTPS requests into ready-to-use code for many languages and tools. Supported languages and formats: * cURL * HTTPie * HAR * Postman Collection 2 * Axios * Dart * Go * Java + HTTPClient * JavaScript + jQuery * Kotlin + OkHttp * Node + HTTP * Node + Fetch * PHP + Guzzle * Python + Request * Rust + reqwest * Objective-C + NSURLSession * Swift + Alamofire 5 * Swift + Moya * Swift + URLSession ![Proxyman Code tab with Swift + Alamofire 5 code generated from a captured GET request](https://proxyman.com/docs/assets/code-generator.png) ## 2. How to open the Code Generator Tab? 1. In the Request panel, click the "+" button 2. The Custom Previewer Tab window appears -> check the **Code Generator** checkbox ![Proxyman Custom Previewer Tab window with Code Generator checked and the Code tab showing Swift code](https://proxyman.com/docs/assets/CleanShot%202025-01-29%20at%203%E2%80%AF.44.21%402x.jpg) _How to open the Code Generator tab_ * A new **Code** tab is added to the Request panel -> select any language to show the code ## 3. Missing your favorite library? If you can't find your library, you can: * Create a [ticket on GitHub](https://github.com/ProxymanApp/Proxyman/issues). * Fork the [Code-Generator-Plugin repository](https://github.com/ProxymanApp/code-generator-plugin) and open a PR. We appreciate your contribution 🙇‍♂️ --- Source: https://proxyman.com/docs/advanced-features/diff # Diff > Compare two HTTP requests or responses with the Proxyman Diff tool, side by side or unified, including the URL, headers, status code, and body. ## 1. What's it? When you use Proxyman, you may need to find the differences between requests or responses. The Diff tool helps you: * Diff two requests or responses, including the URL, method, status code, headers, and text-based body. * Show the diff side by side or unified. * Use a light or dark theme. * Export as a unified diff file. * Open the diff in 3rd-party apps, such as FileMerge. * Highlight and add comments. > **Note:** This feature is only available for macOS 11.2 and later. ## 2. How to use it? 1. Select your requests on the main table view. 2. Right-click -> **Tools** -> **Add to Diff Pool…** (or press ⌘Y) 3. In the Diff window, select the Left and Right requests. 4. Proxyman performs the diff and displays it. You can open the Diff window at any time from the **Diff** menu -> **Open Diff View…** (⌥⌘Y). ### Side-by-Side mode ![Proxyman Diff window comparing two responses in side-by-side mode](https://proxyman.com/docs/assets/Screen%20Shot%202022-03-27%20at%2009.30.03.png) ### Unified Mode ![Proxyman Diff window comparing two requests in unified mode](https://proxyman.com/docs/assets/Screen%20Shot%202022-03-27%20at%2009.31.53.png) ## 3. Open with 3rd-party diff tools * FileMerge: requires Xcode * Kaleidoscope: install the `ksdiff` command-line tool from Kaleidoscope's settings. ## Learn more * [Compare two HTTP requests and responses with the Proxyman Diff tool](https://proxyman.com/posts/2022-05-28-Introduce-Diff-View) --- Source: https://proxyman.com/docs/advanced-features/access-control # Access Control > Use Proxyman Access Control to allow all, block all, or allow only specific IP addresses to connect to your proxy, and set the mode from the CLI. ## 1. What's it? Access Control is an advanced feature that lets you define how remote devices (iPhone, Android, other computers) can connect to the Proxyman app. It's designed for enterprise users who need better security. Open it from the **Tools** menu -> **Proxy Settings** -> **Access Control…**
ModeDescription
Allow AllAll remote connections can connect to Proxyman (Default).
Disallow AllNo remote connections are allowed to connect to Proxyman.
Specify Remote Devices by IPDefine which devices (by IP address) can connect to the Proxyman app.
![Proxyman Access Control window with Specify Remote Devices by IP selected and two allowed IP addresses](https://proxyman.com/docs/assets/proxyman-access-control-window.jpg) _Access Control window_ When **Prompt to allow unauthorized connections** is checked, Proxyman asks you to allow or deny a device that is not on the list. ![Proxyman prompt asking to allow or deny a connection from a remote device IP address](https://proxyman.com/docs/assets/Screenshot%202023-01-19%20at%2014.31.47.png) _Prompt to allow unauthorized connections_ ## 2. Override the Access Control mode by Command Lines From Proxyman 4.4.0, you can override the Access Control mode with the following commands. It's useful if your company wants to enforce a mode without using the app's UI. ``` $ defaults write ~/Library/Preferences/com.proxyman.NSProxy.plist accessControlModeString "allowAll" $ defaults write ~/Library/Preferences/com.proxyman.NSProxy.plist accessControlModeString "disallowAll" $ defaults write ~/Library/Preferences/com.proxyman.NSProxy.plist accessControlModeString "specificIP" ``` --- Source: https://proxyman.com/docs/advanced-features/dns-spoofing # DNS Spoofing > Use Proxyman DNS Spoofing to send a domain to a different IP address or server while keeping the original URL and Host header unchanged. ## 1. What's it? DNS Spoofing lets developers: * Provide a custom DNS for particular domains * Map a domain to a different IP address or domain ![Proxyman DNS Spoofing window with Enable DNS Spoofing checked and a rule that maps api.example.com to 127.0.0.1](https://proxyman.com/docs/assets/proxyman-dns-spoofing-window.jpg) _DNS Spoofing window_ ## 2. What is different with Map Remote? DNS Spoofing is different from [Map Remote](https://proxyman.com/docs/advanced-features/map-remote): * The `Host` in the request header doesn't change * The URL doesn't change On the other hand, Map Remote changes the Host header and the URL to the mapped values. ## 3. How to use it? 1. Open the **Tools** menu -> **DNS Spoofing…** 2. Create a new rule with the **Host Name** and the **New Remote Address** 3. Done ✅ --- Source: https://proxyman.com/docs/advanced-features/socks-proxy # SOCKS Proxy > Turn on the Proxyman SOCKS5 proxy (port 8889 by default) to capture and debug HTTP and HTTPS traffic from apps that support SOCKS proxies. ## 1. What's it? From Proxyman 4.9.0, Proxyman supports a SOCKS proxy in addition to the normal HTTP/HTTPS proxy. * Supports HTTPS over the SOCKS proxy: all debugging tools (e.g. Map Local, Breakpoint, ...) still work. * Compatible with SOCKS 5 > **Note:** Proxyman doesn't automatically override the system SOCKS proxy setting at launch. You have to enable it manually if needed. ## 2. How to use it? 1. Open the **Tools** menu -> **Proxy Settings** -> **SOCKS Proxy Settings…** and check **Enable SOCKS Proxy** 2. By default, Proxyman listens on port 8889. If the port is in use, **Auto select available port** picks a different one. 3. On your client: set the SOCKS proxy to 127.0.0.1 at port 8889 ![Proxyman SOCKS Proxy settings with Enable SOCKS Proxy checked, port 8889 and Auto select available port](https://proxyman.com/docs/assets/proxyman-socks-proxy-settings.jpg) _SOCKS Proxy settings_ --- Source: https://proxyman.com/docs/advanced-features/swagger-openapi # Swagger OpenAPI > Export captured Proxyman requests and responses to a Swagger OpenAPI 3.0 YAML file or an HTML page, with no extra tools to install. ## 1. OpenAPI From Proxyman v5.14.0 or later, Proxyman can export your requests and responses to an OpenAPI 3.0 YAML file or an HTML page. * Supports YAML format * Supports HTML in the Swagger OpenAPI style * Built into Proxyman, no need for any external dependencies. ![Swagger OpenAPI 3.0 HTML page exported from Proxyman, listing GET endpoints captured from x.com](https://proxyman.com/docs/assets/Screenshot%202025-01-06%20at%202.37.25%E2%80%AFPM.jpg) _Export your requests and responses to an OpenAPI HTML page_ ## 2. How to use 1. Capture HTTPS requests with Proxyman. Follow the setup guide for your device: * [iOS devices (iPhone, iPad)](https://proxyman.com/docs/debug-devices/ios-device) * [iOS Simulator](https://proxyman.com/docs/debug-devices/ios-simulator) * [Android devices](https://proxyman.com/docs/debug-devices/android-device#1-android-setup-guide) * [Android Emulator](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) * [macOS (Web Browser)](https://proxyman.com/docs/debug-devices/macos) Make sure Proxyman can capture and decrypt your HTTPS requests and responses. ![Export > OpenAPI](https://proxyman.com/docs/assets/proxyman-export-openapi-menu.jpg) _Export > OpenAPI_ 2. Select your requests on the main table -> right-click -> **Export** -> **OpenAPI** -> select **YAML Schema…** or **HTML…** 3. Done :white\_check\_mark: ## Learn more * [Generate OpenAPI 3.0 for reverse engineering REST APIs in a few clicks](https://proxyman.com/posts/2025-01-09-Generate-OpenAPI-YAML) * [Proxyman vs mitmproxy: Generate OpenAPI from captured traffic](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Generate-OpenAPI) --- Source: https://proxyman.com/docs/advanced-features/tls-key-logging # TLS Key Logging > Record TLS session keys with Proxyman TLS Key Logging and save them to a file, so you can decrypt HTTPS traffic in Wireshark or TCP Viewer. ## 1. What's it? Proxyman can log TLS session keys and save them to a txt file, so you can decrypt HTTPS traffic in Wireshark or the [TCP Viewer](https://tcpviewer.proxyman.com/) app. ## 2. How to use it 1. Open Proxyman for macOS 2. Make sure the Proxyman certificate is installed on your Mac: open the **Certificate** menu -> **Install Certificate on this Mac…** and follow the guide 3. Open the **Tools** menu -> **TLS Key Logging…** 4. Check **Enabled TLS Key Logging**, click **Select Folder…** to choose where to save the log file, then click **Save** ![Proxyman TLS Key Logging sheet with logging enabled and the Desktop folder selected as the file path](https://proxyman.com/docs/assets/Screenshot%202026-09-03%20at%2012.40.51.png) _TLS Key Logging settings_ 5. Done. When Proxyman captures your traffic, it extracts the TLS keys and saves them to the log file. * For an iOS device, follow [ios-device.md](https://proxyman.com/docs/debug-devices/ios-device) to set up your iPhone/iPad * For an Android device, follow [android-device](https://proxyman.com/docs/debug-devices/android-device) * For an Android Emulator, follow [google-play-android-emulator-with-magisk.md](https://proxyman.com/docs/debug-devices/android-device/google-play-android-emulator-with-magisk) --- Source: https://proxyman.com/docs/proxyman-windows/install-certificate # Install Certificate > Install and trust the Proxyman CA certificate on Windows 10 and 11, with the automatic script or by hand, so Proxyman can decrypt HTTPS traffic. ## Install Certificates on Windows To intercept encrypted HTTPS messages (Request or Response), you have to install the **Proxyman CA Certificate** on your Windows machine. You can install the Proxyman CA Certificate from * **Certificate** menu -> **Install Certificate on this Windows**... > **Note:** The Proxyman Certificate is a self-signed certificate, which is generated on your machine. Proxyman never stores or sends any personal data to Proxyman's server or any 3rd party. > > Please check out the [Proxyman Privacy Statement](https://proxyman.com/privacy) to see what data Proxyman collects. > > If you'd like to generate a Certificate on your machine by hand and then add it to Proxyman, please check out the [Custom Certificate Doc](https://proxyman.com/docs/advanced-features/custom-certificates#6-how-to-generate-self-signed-certificates-for-custom-root-certificate-that-comply-with-new-apples-security-requirements) ## 1. Automatic mode ![Proxyman for Windows Install Certificate dialog showing the certificate as Installed and Trusted](https://proxyman.com/docs/assets/Screenshot%202023-01-23%20at%2009.38.09.png) _Auto install the certificate on Windows machine_ Proxyman provides an automatic script to install and trust the Proxyman CA Certificate in the System. * Certificate Menu -> Install Certificate for this Windows -> Click on the "Install & Trust" button * Click YES on the System Prompt ![Windows User Account Control prompt for Windows Command Processor with the Yes button](https://proxyman.com/docs/assets/Screenshot_2023-01-23_at_09_41_41.jpg) _Grant permission to run the Automatic Script_ ### Why do I need to grant permission? Behind the scenes, Proxyman runs the following command as Administrator: ```bash $ certutil -addstore "Root" ``` > **Note:** [certutil](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/certutil) is a built-in Windows command line to manage the certificate. ## 2. Manual Mode If you don't have permission to run the script, please follow these steps: 1. Close Proxyman 2. Find a Proxyman CA Certificate at "C:\Users\\\\AppData\Roaming\Proxyman\certificate\certs\ca.cer" 3. Double-click to open it 4. Install Certificate -> Select "Current User" -> Select "Place all certificates in the following store" -> "Browse..." -> Select "Trusted Root Certification Authorities" -> OK ![Windows Certificate Import Wizard placing the certificate in the Trusted Root Certification Authorities store](https://proxyman.com/docs/assets/212792551-e3875685-294b-46b4-b563-b3c7051fb29a.jpg) _Steps to install the certificate_ 5\. Select Next -> Finish 6\. Select "YES" on the System Prompt. --- Source: https://proxyman.com/docs/proxyman-windows/wsl # WSL > Install WSL, Chocolatey (choco) and adb on Windows 10 or 11 so you can use the Proxyman automatic script for Android Emulators. ## 1. What's it? To use the Automatic Script for Android Emulator in Proxyman for Windows, the following command-line tools must be installed on your Windows machine: * wsl * choco (package manager for Windows) * adb (Android Debug Bridge) ## 2. Install WSL on Windows 10/11 1. On Windows 10/11, search: **Command Prompt** app 2. Right-click on the app -> Select **Run as administrator** option. 3. When the app opens, copy and paste the following command: ```bash wsl --install ``` 4. Restart Windows to apply the change -> After restarting, Windows opens the **Command Prompt** and asks you to create a new Username / Password -> Follow the instructions 5. Open the Command Prompt app again and run: ``` wsl ``` 6. Verify that the command is successful, with no errors: ![Windows Terminal after running wsl, showing the Linux shell prompt with no errors](https://proxyman.com/docs/assets/CleanShot%202024-03-29%20at%209%E2%80%AF.43.29%402x.jpg) 7. Done ✅ ## 3. Install **Choco** on Windows 10/11 1. Open PowerShell with Run as Administrator 2. Paste and run it: ``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) ``` 3. Wait a few seconds for the command to complete. 4. If you don't see any errors, you are ready to use Chocolatey! Type `choco` or `choco -?` to check it. Choco Installation Guide: [https://chocolatey.org/install#individual](https://chocolatey.org/install#individual) ## 4. Install **adb** on Windows 10/11 1. Open PowerShell with Run as Administrator 2. Run: ``` choco install adb -y ``` 3. Verify that **adb** is installed and there is no error ## 5. ✅ Done. Try the Android Automatic Script again in the Proxyman app ## 6. References: * [https://learn.microsoft.com/en-us/windows/wsl/install](https://learn.microsoft.com/en-us/windows/wsl/install) * [https://pureinfotech.com/install-wsl-windows-11/#install\_wsl2\_single\_command](https://pureinfotech.com/install-wsl-windows-11/#install\_wsl2\_single\_command) --- Source: https://proxyman.com/docs/scripting/script # Scripting > Use the Proxyman Scripting tool to modify HTTP requests and responses with JavaScript, mock APIs, and log WebSocket messages with onWebsocket. ## 1. What's it? Proxyman offers a Scripting tool. You can write JavaScript code to change the request and response in a flexible way. ## 2. Benefits * Implement Map Local / Map Remote / Breakpoint with JS code. **100x Faster** * Change the **Request Content**, including Domain, Host, Scheme, Port, Path, HTTP Method, HTTP Headers, Query, Body (Encoded-Form, JSON, plain-text) * Log and inspect WebSocket messages with `onWebsocket` (**Proxyman 26.1.0 or later for macOS, Windows and Linux**). * [Edit, drop, or send WebSocket messages](https://proxyman.com/docs/scripting/modify-websocket-messages) with `onWebsocket` (**macOS Proxyman 26.2.0 or later, Windows/Linux Proxyman 26.1.0 or later**). * Change the **Response Content**, including HTTP Status Code, HTTP Headers, and Body (JSON, Encoded-Form, plain-text, binary...) * Plenty of built-in addons and libraries for common tasks, such as Hashing, Encode/Decode, JSON-Text transformer, Beautify, ... * **Write your own JS Addons or Libraries** * Designed to replace Rewrite GUI Tool from Charles Proxy * Share state between scripts in the current session with [Shared State or Environment Variables](https://proxyman.com/docs/scripting/environment-variables) ![Proxyman Script Editor with a POST rule, Request and Response checked, Run as Mock API, and onRequest and onResponse code](https://proxyman.com/docs/assets/proxyman-script-editor.jpg) _Scripting Tool_ - [Snippet Code](https://proxyman.com/docs/scripting/snippet-code) ## 3. How to use it? You can access the Scripting Tool by: * **Scripting** menu -> **Script List…** (⌥⌘I) * Right-click a flow -> **Tools** -> **Scripting…** Check out the [Snippet Code](https://proxyman.com/docs/scripting/snippet-code) page for a collection of JS snippets for the Scripting Tool. ## 4. Scripting with GraphQL Requests From Proxyman 2.27.0+, the Scripting Tool can match a GraphQL request by its QueryName. Check out the following GraphQL document. - [GraphQL](https://proxyman.com/docs/advanced-features/graphql) ## 4.1 Scripting with Websocket From Proxyman 6.2.0 for macOS, use `onRequest` and `onResponse` to modify the WebSocket request URL and handshake headers. See [Change the WebSocket URL and headers](https://proxyman.com/docs/scripting/snippet-code#change-websocket-url-requestsresponse-header). ### Log messages with onWebsocket > **Warning:** `onWebsocket` is available in **Proxyman 26.1.0 or later for macOS, Windows and Linux**. It is not available on iOS. Use `onWebsocket(context, url, request, response, message)` to inspect and log captured messages from both the client and the server: ```javascript function onWebsocket(context, url, request, response, message) { console.log(`[${message.from}] ${message.type}: ${message.data}`); } ``` By default, this hook is **read-only**. Proxyman forwards the message before running the script. Changing its arguments or returning a value does not modify the traffic or captured messages. No return statement is required. To edit, drop, or send messages, check **Modify WebSocket Messages** on the rule (macOS Proxyman 26.2.0 or later, Windows/Linux Proxyman 26.1.0 or later). See [Modify WebSocket Messages](https://proxyman.com/docs/scripting/modify-websocket-messages). **How to use it** 1. Capture a WebSocket connection. For `wss://`, enable SSL Proxying for the host so Proxyman can read its messages. 2. Right-click the captured flow and select **Tools → Scripting**. The generated script includes `onWebsocket` below `onResponse`. 3. Add your logging code and click **Save & Activate**. 4. Reconnect the WebSocket, send messages, and check the script's **Console Log**. The rule must be active when the connection opens. Reconnect after creating a rule or adding `onWebsocket` to a script that did not have it when the connection opened. The ordinary new-script template does not include this hook; you can add it manually. **Arguments** Keep all five arguments in order. `context` and `url` describe the flow and matching rule. `request` and `response` contain the final handshake, including changes made by `onRequest`, `onResponse`, or Breakpoint. `message` contains: | Field | Value | | --- | --- | | `message.type` | `"text"`, `"binary"`, `"ping"`, `"pong"`, or `"close"`. | | `message.from` | `"client"` or `"server"`. | | `message.data` | Always a string. Binary data is shown as UTF-8 text when possible, otherwise `Binary (length=N)`. Optional WebSocket tab decoders are not applied. | | `message.rawData` | A copied `Uint8Array`, available only for binary messages. Log it explicitly; it is not included when enumerating `message`. | | `message.closeCode` | A number, available only for close messages, such as `1000`. | **Notes** * Fragmented text and binary frames are reassembled before the hook runs. You receive one complete message, not a separate callback for each continuation frame. * Ping/pong payloads and close reasons are not exposed. * Synchronous and `async` hooks are supported, along with helpers such as `console.log`, `require`, `sharedState`, and `$http`. * Edits to an existing hook and rule/folder/tool enabled state are checked at most once per second as messages arrive. Calls already queued may finish. * The Console Log keeps the latest 200 log entries. If scripts cannot keep up, hook calls may be skipped with a warning while traffic continues. Use it for debugging, not as a complete traffic archive. See [WebSocket message snippets](https://proxyman.com/docs/scripting/snippet-code#log-websocket-messages-with-onwebsocket) for text, JSON, binary, ping/pong, and close examples. ## 5. Examples The following guide shows how to write JS code to change the request domain from production to localhost and change the response body. 1. Make sure you enable SSL Proxying for this domain before creating the script. 2. Open the Scripting Tool and create a new Script Entry (⌘N). You can also right-click the request -> Tools -> Scripting… => Proxyman creates a script for you. 3. Give it a name and define a Matching Rule. 4. Ex: **Name**=Test on Localhost endpoint, **URL**=https://proxyman.io 5. Enable the **Request** and **Response** checkboxes in **Run Script on** 6. Start writing JS code for `onRequest` function **onRequest(context, url, request) {}** ```javascript // Import UUID addons const { uuidv4 } = require("@addons/UUID.js"); function onRequest(context, url, request) { // print log console.log(request); // Change Production domain -> Localhost request.method = "GET"; request.scheme = "http"; request.host = "localhost"; request.port = 8000; // Add new header request.headers["X-New-Header"] = "Hello From Scripting feature"; request.headers["UUID"] = uuidv4(); // generate random UUIDv4 delete request.headers["Key-Need-Delete"]; // Update or Add a new Query request.queries["name"] = "Proxyman"; // Update Body var body = request.body; body["name"] = "Proxyman"; request.body = body; // Or Map the body with a local file (Proxyman 2.25.0+) // request.bodyFilePath = "~/Desktop/mockdata.json"; // Done return request; } ``` ## onRequest() Object Format `context`, `url` and `request` Objects are defined by: ```javascript // context (readonly) { "scriptName": " Your Script Name", "matchingRule": " Your Matching Rule", "matchingMethod": " Method", "isEnableOnRequest": "Bool", "isEnableOnResponse": "Bool", "filePath": " Script path", "flow": { // Available from 2.16.0+ "serverPort": "443", "serverIpAddress": "104.18.230.83", "clientIpAddress": "192.168.0.102", "remoteDeviceName": "iPhone XR", "remoteDeviceIP": "192.168.0.102", "id": "51", "clientPath": null, "clientPort": "51494", "clientName": null, "mapRemoteOriginalURL": " Original URL before Map Remote modification (nullable)" }, } // url (readonly) url: String // => Present the full URL // request { "method": " HTTP Method. Accept string method. Ex: GET, POST, ...", "scheme": " Accept http or https", "host": " Host of the request. Ex: api.proxyman.io, localhost, ...", "path": ": Path of the URL. Ex: /v1/data", "port": " Accept int port number. Ex: 443, 8080, ..", "queries": "<[String: Any]> A JS Object (Dictionary) contains key values of the query", "headers": "<[String: Any]> A JS Object (Dictionary) contains key values of the header", "body": "Depend on the Content-Type header. It might be a dictionary for JSON and form, Plain Text or Uint8Array", "bodyFilePath": " Set a body with a local file. See example in Snippet Code Page" "rawBody": ": A raw body String or Uint8Array", "preserveHostHeader": " Preserve the Host", "isURLEncoding": " Determine if Proxyman will perform URLEncoding when constructing the final URL. Default is True", "upstream": " Upstream TLS ALPN and HTTP/2 settings. Proxyman v26.0.0 or later for macOS." } ``` > **Note:** You can change any value of the request obj except `rawBody` Set `request.upstream` in `onRequest`. See [Upstream ALPN and HTTP/2 settings](https://proxyman.com/docs/scripting/snippet-code#upstream-alpn-and-http2-settings) for an example and supported fields. > **Note:** If the **body** has an invalid format because of an incorrect Content-Type header, use **rawBody** and parse the string manually. The type of `request.body` depends on the Content-Type header. | Content-Type Header | request.body | | ----------------------------------------------------------------------------------- | ----------------- | | application/json or JSON families | Javascript Object | | application/x-www-form-urlencoded | Javascript Object | | plain-text or text-based Content-Type, Ex: application/js, text/css, text/html, ... | String | | The rest: Binary Data (application/zip, application/octet-stream) | Uint8Array | Check out common JS code on the Snippet Code page: - [Snippet Code](https://proxyman.com/docs/scripting/snippet-code) 7\. Start writing code on `onResponse` function ```javascript function onResponse(context, url, request, response) { console.log(response); // Update or Add a new header response.headers["Content-Type"] = "application/json"; // Update status Code response.statusCode = 500; // Update Body var body = response.body; body["new-key"] = "Proxyman"; response.body = body; // Or Map the body with a local file (Proxyman 2.25.0+) // response.bodyFilePath = "~/Desktop/mockdata.json"; // Done return response; } ``` ## onResponse() Objects Format `context`, `url`, `request`, and `response` objects are defined by: ```javascript // context (readonly): Same with onRequest // url (readonly): Same with onRequest // request (readonly): Same with onRequest // response { "statusCode": " Status Code. Ex: 200, 400, 404,...", "httpVersion": " The HTTP Version", "statusPhrase": " HTTP Status Phrase. Ex Not Found, OK, ...", "headers": "<[String: Any]> A JS Object (Dictionary) contains key values of the header", "body": "Depend on the Content-Type header. It might be a dictionary for JSON and form, PlainText or Uint8Array", "rawBody": ": A raw body String or Uint8Array", "bodyFilePath": " Set a body with a local file. See example in Snippet Code Page" } ``` > **Note:** You can change `statusCode`, `headers` and `body` from the response Obj > **Note:** If the **body** has an invalid format because of an incorrect Content-Type header, use **rawBody** and parse the string manually. The type of `response.body` depends on the Content-Type header. | Content-Type Header | response.body | | ----------------------------------------------------------------------------------- | ----------------- | | application/json or JSON families | Javascript Object | | application/x-www-form-urlencoded | Javascript Object | | plain-text or text-based Content-Type, Ex: application/js, text/css, text/html, ... | String | | The rest (application/zip, application/octet-stream) | Uint8Array | > **Note:** You must return the `request` and `response` objects in the `onRequest` and `onResponse` functions. ## 6. Built-in Addons and Libraries Proxyman provides plenty of addons and libraries for common tasks: Hashing, Encode/Decode, ... - [Addons](https://proxyman.com/docs/scripting/addons) - [Built-in JS Libraries](https://proxyman.com/docs/scripting/built-in-js-libraries) - [Snippet Code](https://proxyman.com/docs/scripting/snippet-code) ## 7. Debugging JS Error Sometimes you might get JavaScript errors because of syntax errors, invalid code, etc. You can debug by reading the error messages in the console or by using `console.log()`. ## 8. Use Scripting as a Mock API From Proxyman 2.32.0, you can use the Scripting Tool as a Mock API. Your request never hits the server, and you define the response body yourself. This works the same way as Map Local. This is useful when the real REST API is not available yet. You can define and test it locally. To enable the Mock API: 1. Open the Scripting Tool -> Select the Script 2. Enable the **Run as Mock API** checkbox, next to the **Request** and **Response** checkboxes in the Script Editor (see the Script Editor screenshot above). Then you can define a Response as usual: ```javascript function onResponse(context, url, request, response) { // Init new body var body = {}; body["new-key"] = "Proxyman"; response.body = body; // Or map from a file // response.bodyFilePath = "~/Desktop/myfile.json" // Done return response; } ``` ## 9. Notes * You must return the `request` and `response` objects in the `onRequest` and `onResponse` functions. * **Proxyman 4.16.0 or later**: Proxyman now converts the Binary Data to **Uint8Array** * Proxyman 4.15.0 or earlier: JavaScript doesn't have a Data type, so a binary body is converted to a **Base64 Encoded String** in JavaScript. To pass a Uint8Array, blob, or ArrayBuffer to the body, convert it to a **Base64 Encoded String** first. ## Learn more * [How to map a Local Response for GraphQL Requests?](https://proxyman.com/posts/2021-01-24-How-To-Map_Response_For_GraphQL_Requests) * [How to by-pass CORS Policy](https://proxyman.com/posts/2020-08-31-How-to-by-pass-CORS-policy) --- Source: https://proxyman.com/docs/scripting/modify-websocket-messages # Modify WebSocket Messages > Edit, drop, or send WebSocket (WS/WSS) messages on the fly with onWebsocket in Proxyman Scripting. Works in both directions, with text and binary messages. ## 1. What's it? With the **Modify WebSocket Messages** option, the `onWebsocket()` function of a script can change WebSocket messages on the fly. With a few lines of JavaScript, you can: * Edit a message, for example change a JSON field or replace text. * Drop a message, so the other side never sees it. * Send a new message to the client or the server. * Close the WebSocket on both sides. It works with WS and WSS, in both directions: from the client to the server, and from the server to the client. > **Note:** Modify WebSocket Messages is available in **macOS Proxyman 26.2.0 or later** and **Windows/Linux Proxyman 26.1.0 or later**. It is not available on iOS.

The server sends a real BTC price, but the app receives $1. A message with a password is dropped, and the app gets a warning from the script.

## 2. The problem Apps for chat, trading, games, and live dashboards use WebSocket to get real-time data. Testing them is hard: * **You can't control the server.** It sends real data. Making it send an edge case, like a price of 0 or an error message, means changing the server code. * **Some cases are hard to reproduce.** A dropped message, a strange reply, or a lost connection rarely happens when you need it. * **Other tools can't change messages.** [Breakpoint](https://proxyman.com/docs/advanced-features/breakpoint) and [Map Local](https://proxyman.com/docs/advanced-features/map-local) work on the HTTP handshake, not on the messages after it. Without the option, `onWebsocket()` only reads the messages. ## 3. Benefits * Test every message your app should handle, without changing the server. * Mock a server reply: answer a message of the client with `sendToClient()`. The server never sees it. * Hide sensitive data or block analytics events before they reach the server. * Simulate a lost connection to test how your app reconnects. * Only the WebSocket that matches the rule waits for the script. Other traffic keeps flowing. ## 4. How to use it? 1. Capture your WebSocket connection. For `wss://`, enable [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain, like for HTTPS. 2. Right-click the `ws://` or `wss://` flow -> **Tools** -> **Scripting…**. Proxyman creates a rule with the URL filled in, and a script with `onWebsocket()`. 3. Keep **Request** checked, and check **Modify WebSocket Messages**. 4. Write your `onWebsocket()` code, then press **Save & Activate** (⌘S, or Ctrl+S on Windows/Linux). 5. Reconnect the WebSocket. Proxyman reads the option when the WebSocket connects, not for every message. ![The Proxyman Script Editor with Modify WebSocket Messages checked and an onWebsocket() script](https://proxyman.com/docs/assets/script-editor-modify-websocket-messages.jpg) _Check Modify WebSocket Messages in the Script Editor_ This script makes every BTC price from the server $1, and drops a message from the client that has a password: ```javascript function onWebsocket(context, url, request, response, message) { // Only change text messages. Binary, ping, pong, and close messages pass through if (message.type !== "text") { return message; } const json = JSON.parse(message.data); // 1. Server -> client: every BTC price becomes $1 if (message.from === "server" && json.type === "price") { json.price = 1; json.note = "edited by Proxyman"; message.data = JSON.stringify(json); return message; } // 2. Client -> server: drop a message with a password, and warn the client if (message.from === "client" && json.text.includes("password")) { sendToClient(JSON.stringify({ type: "warning", text: "Proxyman blocked a password" })); return null; } // 3. Everything else: send it as it is return message; } ``` The **Websocket** tab shows the edited messages, the messages sent by the script, and the dropped messages: ![The Proxyman main window with the ws://localhost:3456/prices flow and its edited WebSocket messages](https://proxyman.com/docs/assets/websocket-tab-edited-messages.jpg) _Edited and dropped messages in the Websocket tab_ For a step-by-step guide with a local WebSocket server that you can run yourself, read [How to modify WebSocket messages with Scripting](https://proxyman.com/posts/2026-10-23-modify-websocket-messages-with-scripting). ## 5. What onWebsocket() returns When the option is on, Proxyman holds each text and binary message until `onWebsocket()` returns. What you return decides what happens: | In `onWebsocket()` | Result | | --- | --- | | `return message` | Send the message, with your changes. | | `return null` | Drop the message. The other side never sees it. | | No return | Send the original message. | | `abort()` | Close the WebSocket on both sides. | | `sendToClient(data)` / `sendToServer(data)` | Send a new message. A String sends a text message, a `Uint8Array` a binary message. | The `message` object has: | Field | Value | | --- | --- | | `message.from` | `"client"` or `"server"`. | | `message.type` | `"text"`, `"binary"`, `"ping"`, `"pong"`, or `"close"`. | | `message.data` | The text of the message. Change it to edit a text message. | | `message.rawData` | The bytes of a binary message, as a `Uint8Array`. Set a new `Uint8Array` to edit a binary message. | | `message.closeCode` | A number, available only for close messages, such as `1000`. | See [Scripting with WebSocket](https://proxyman.com/docs/scripting/script#41-scripting-with-websocket) for the other arguments. > **Note:** The option is off by default. When it's off, `onWebsocket()` works as before: it only reads the messages and never delays them. ## 6. Templates You don't need to write the script from scratch. In the Script Editor, click **Templates** and search for "websocket": * **Log WebSocket Messages**: print every message in the Console Log. It only reads the messages. * **Modify JSON WebSocket Messages**: change a field of the JSON messages from the server. * **Replace Text in WebSocket Messages**: find and replace text in both directions. * **Drop WebSocket Messages**: drop the messages that match a regex, for example analytics events. * **Reply to a WebSocket Message**: answer a message of the client with `sendToClient()`. The server never sees it. * **Simulate a WebSocket Disconnect**: close the WebSocket after a few messages. Click **Replace** to use a template. Proxyman also sets the checkboxes it needs, including **Modify WebSocket Messages**. ![The Script Templates sheet in Proxyman, filtered to the WebSocket templates](https://proxyman.com/docs/assets/websocket-script-templates.jpg) _WebSocket templates in the Script Editor_ More examples are on the [Snippet Code](https://proxyman.com/docs/scripting/snippet-code#modify-websocket-messages-with-onwebsocket) page. ## 7. Good to know * You can edit and drop text and binary messages. Ping, pong, and close messages are always sent: `onWebsocket()` can read them, but what it returns is ignored. * A message keeps its type: you can't turn a text message into a binary message. * If your script throws an error, or doesn't return within 30 seconds, Proxyman sends the original message and prints the error in the Console Log. * The code outside `onWebsocket()` runs once per connection, so a counter at the top of the script counts the messages of each connection. * Messages sent with `sendToClient()` and `sendToServer()` don't run `onWebsocket()` again, so a script that replies can't loop forever. * When several scripts with the option match the same WebSocket, they run in order: each one receives what the previous one returned. A dropped message doesn't reach the next scripts. * A message bigger than 16 MB is sent as it is, without the script. * `async` functions are supported, so you can use `await` and [$http](https://proxyman.com/docs/scripting/async-await-request) in `onWebsocket()`. * AI agents can create the same rule with [Proxyman MCP](https://proxyman.com/docs/mcp): `create_scripting_rule` takes `modify_websocket_messages: true`. ## 8. Troubleshooting ### The messages don't change * Check **Modify WebSocket Messages**, then press **Save & Activate** (⌘S, or Ctrl+S on Windows/Linux). * Reconnect the WebSocket. The option is read when the WebSocket connects. * Keep **Request** or **Response** checked. A rule with both unchecked doesn't run at all, including `onWebsocket()`. * Return `message` after you change it. Without a return, Proxyman sends the original message. * Open the Console Log in the Script Editor and look for errors. ### I can't see my WebSocket in Proxyman Follow the [WebSocket](https://proxyman.com/docs/advanced-features/websocket) guide for your platform. Many apps and libraries skip the proxy for `localhost`. --- Source: https://proxyman.com/docs/scripting/async-await-request # async/await Request > Use async/await in Proxyman Scripting to call external HTTP/HTTPS APIs from onRequest and onResponse, with $http on macOS or axios on Windows/Linux. ## 1. What's it? From Proxyman macOS v3.5.0 and Windows/Linux v2.11.0 or later, you can use `async / await` to make an HTTP/HTTPS call and fetch external resources inside your script. > **Note:** > > * On macOS: Use \`$http\` > * On Windows/Linux: Use built-in \`axios\` ### Sample: POST Request with JSON Body (macOS) ```javascript async function onResponse(context, url, request, response) { // Define JSON Body and Header // Make sure "Content-Type" is "application/json" var param = { body: { "user": { "name": "Proxyman" } }, headers: { "Content-Type": "application/json" } } // POST request with await var output = await $http.post("https://httpbin.org/post", param); // Get Status Code console.log(output.statusCode); // Get body console.log(output.body) // Get header console.log(output.headers) // Done return response; } ``` ## 2. How to use on macOS? ### Method ```javascript var output = await $http.get("https://httpbin.org/anything"); var output = await $http.post("https://httpbin.org/anything"); var output = await $http.put("https://httpbin.org/anything"); var output = await $http.patch("https://httpbin.org/anything"); var output = await $http.delete("https://httpbin.org/anything"); ``` ### Output format ```javascript var output = await $http.get("https://httpbin.org/anything"); console.log(output) // print { "statusCode": , "headers": , "body": } ``` ### Sample Code * [GET Request with Query](https://proxyman.com/docs/scripting/snippet-code#get-request-with-query) * [POST Request with JSON Body](https://proxyman.com/docs/scripting/snippet-code#post-request-with-json-body) * [POST Request with application/x-www-form-urlencoded body](https://proxyman.com/docs/scripting/snippet-code#post-request-with-applicationx-www-form-urlencoded-body) * [PUT / PATCH / DELETE Request](https://proxyman.com/docs/scripting/snippet-code#put--patch--delete-request) > **Note:** Check out the [async/await HTTP request snippets](https://proxyman.com/docs/scripting/snippet-code#make-asyncawait-http-request-macos) for more sample code. ## 3. How to use on Windows/Linux? Proxyman for Windows/Linux ships with a built-in [axios](https://github.com/axios/axios) library, so you can use the axios syntax to make HTTP(s) requests. For example: ```javascript async function getUser() { try { const response = await axios.get('/user?ID=12345'); console.log(response); } catch (error) { console.error(error); } } ``` ## 4. Notes * Make sure you define `onRequest()` and `onResponse()` as **async** functions: ```javascript async function onRequest(context, url, request) { var output = await $http.get("https://httpbin.org/get"); return request; } async function onResponse(context, url, request, response) { var output = await $http.get("https://httpbin.org/get"); return response; } ``` * The request timeout is 10 seconds. * The inline HTTP request doesn't go through the Proxyman proxy, so other debugging tools don't affect it. * You can use `await $http.get()` in both `onRequest()` and `onResponse()` * Make sure the body type matches the Content-Type header. **JSON Body with application/json** ```javascript var param = { body: { "name": "Proxyman", }, headers: { "Content-Type": "application/json" } } ``` **Encoded form Body with application/x-www-form-urlencoded** ```javascript var param = { body: { "key1": "value1", "key2": "value2" }, headers: { "Content-Type": "application/x-www-form-urlencoded" } } ``` --- Source: https://proxyman.com/docs/scripting/addons # Addons > Browse the built-in Proxyman Scripting addons for Base64, MD5/SHA hashing, UUID, JWT decode, GZip and more, and import them with require(). ## 1. What's it? Proxyman provides handy built-in addons for common tasks, such as MD5 and SHA1 hashing, Base64 encode/decode, and beautifying XML and JSON. > **Tip:** From Proxyman macOS 6.10.0 or later, you can use the native \`npm install\` to install your 3rd-party libraries. See [use-npm-install.md](https://proxyman.com/docs/scripting/use-npm-install). ## 2. Built-in Addons You can find sample code for all addons at [Addons Snippet Code](https://proxyman.com/docs/scripting/snippet-code) | Name | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | [Base64.js](https://proxyman.com/docs/scripting/snippet-code#use-base64-addon) | Base64 encode/decode. Supports native atob/btoa functions | | CamelCase.js | Convert text to Camel Case | | CryptoJS.js | DES, AES, Rabbit encryption/decryption algorithm. A small wrapper of CryptoJS | | DateToTimestamp.js | Convert String Date to Timestamp | | DateToUTC.js | Convert String Date to UTC String | | DecodeURI.js | Decode percent-encoded String | | EncodeURI.js | Encode to percent-encoded String | | FormatCSS.js | Beautify CSS String | | FormatJSON.js | Beautify JSON String | | BeautifyJSON.js | Convert JSON Object to a pretty JSON String | | UglifyJSON.js | Convert JSON Object to a compact JSON String | | FormatXML.js | Beautify XML String | | HelloWorld.js | Hello World | | Hex2rgb.js | Convert #000000 string to RGB string | | JsonToQuery.js | Convert JSON Object to Query String | | JSONValidator.js | Validate JSON String | | [JWTDecode.js](https://proxyman.com/docs/scripting/snippet-code#jwt-decode) | Decode JWT Token | | KebabCase.js | Convert to Kebab Case | | [MD5.js](https://proxyman.com/docs/scripting/snippet-code#use-hashing-addon-md5-sha1-sha256-sha512) | Hash MD5 | | MinifyCSS.js | Minify CSS String | | MinifyJSON.js | Minify JSON String | | MinifyXML.js | Minify XML String | | QueryToJson.js | Convert Query String to JSON Object | | [Pako.js](https://proxyman.com/docs/scripting/snippet-code#deflateinflate-and-gzipungzip) | Deflate/Inflate and GZip/UnGZip | | [SHA1.js](https://proxyman.com/docs/scripting/snippet-code#use-hashing-addon-md5-sha1-sha256-sha512) | Hash SHA1 | | [SHA256.js](https://proxyman.com/docs/scripting/snippet-code#use-hashing-addon-md5-sha1-sha256-sha512) | Hash SHA256 | | [SHA512.js](https://proxyman.com/docs/scripting/snippet-code#use-hashing-addon-md5-sha1-sha256-sha512) | Hash SHA512 | | SnakeCase.js | Convert to Snake Case | | StartCase.js | Convert to Start Case | | [UUID.js](https://proxyman.com/docs/scripting/snippet-code#use-uuid-v4-addon) | Generate Unique UUID-v4 string | ## 3. How to use addons? Each addon exports functions that you can import with the `require` function. For example, the Base64.js addon looks like this: ```javascript // Base64.js const Base64 = require('@libs/base64.js'); const { atob } = require("@libs/atob.js"); const { btoa } = require("@libs/btoa.js"); // atob / btoa // They're equivalent with window.atob and window.btoa exports.atob = atob; exports.btoa = btoa; // Basic Base64 exports.base64Decode = (input) => { return Base64.decode(input) }; exports.base64Encode = (input) => { return Base64.encode(input); }; ``` Then, you can use it in the script: ```javascript const { atob, btoa } = require("@addons/Base64.js") function onRequest(context, url, request) { // Encode base64 by using the export function var text = btoa("Hello World"); console.log(text) // => SGVsbG8gV29ybGQ= } ``` > **Note:** You can find all addons code at **\~/Library/Application\ Support/com.proxyman.NSProxy/addons** ## 4. Notes > **Note:** The `require` function is not a built-in function from [JavascriptCore framework](https://developer.apple.com/documentation/javascriptcore), it's a custom function that Proxyman provides so you can import addons and libraries easily. > > Thanks to [Ivan Mathy](https://github.com/IvanMathy) for creating Boop app that facilitates Proxyman's built-in add-ons. > **Note:** The addons folder is overwritten by every Proxyman update, so don't edit the addons there. To change an addon, copy it to the **users** folder first. See [Write your own Addons](https://proxyman.com/docs/scripting/write-your-own-addons). --- Source: https://proxyman.com/docs/scripting/built-in-js-libraries # Built-in JS Libraries > See the JavaScript libraries bundled with Proxyman Scripting, such as lodash, crypto-js and hashes, and learn how to import your own library with require(). ## 1. What's it? Proxyman bundles some useful JS libraries to help you do common tasks easily. > **Note:** Library Location: **\~/Library/Application\ Support/com.proxyman.NSProxy/addons/libs** > **Tip:** From Proxyman macOS 6.10.0 or later, you can use the native \`npm install\` to install your 3rd-party libraries. See [use-npm-install.md](https://proxyman.com/docs/scripting/use-npm-install). ## 2. Built-in Libraries | Name | Description | Source | | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | base64.js | Contains basic Base64 Encode/Decode | - | | atob.js | window.atob() | [https://github.com/jsdom/abab](https://github.com/jsdom/abab) | | btoa.js | window.btoa() | [https://github.com/jsdom/abab](https://github.com/jsdom/abab) | | hashes.js | Contains various hashing function: MD5, RIPEMD-160, SHA1, SHA256, SHA512, HMAC | [https://github.com/h2non/jshashes](https://github.com/h2non/jshashes) | | lodash.js | Contains various text transformed functions | [https://lodash.com](https://lodash.com) | | vkBeautify.js | pretty-print or minify text in XML, JSON, CSS and SQL formats. | [https://github.com/kayhadrin/vkBeautify/](https://github.com/kayhadrin/vkBeautify/) | | crypto-js.min.js | JavaScript implementations of standard and secure cryptographic algorithms, e.g. DES, AES, Rabbit, ... (Version 3.3.0) | [https://cryptojs.gitbook.io/docs/](https://cryptojs.gitbook.io/docs/) | | pako.js | zlib port for Deflate/Inflate and GZip/UnGZip (Version 1.0.11) | [https://github.com/nodeca/pako](https://github.com/nodeca/pako) | ## 3. How to import my own JS Library? 1. You can provide your own JS Library, but make sure you bundle all dependencies by using [Browserify](http://browserify.org) or [WebPack](https://webpack.js.org) to a single JS file. 2. Make sure you export the functions properly. 3. Put the file at **\~/Library/Application\ Support/com.proxyman.NSProxy/addons/libs/your-lib.js** 4. Import the file with: ```javascript require('@libs/your-lib.js'); ``` For instance, ```javascript const Hashes = require('@libs/hashes.js'); const { cssmin } = require('@libs/vkBeautify.js'); const Lodash = require('@libs/lodash.js'); const { atob } = require('@libs/atob.js') ``` > **Note:** You might check built-in libraries for reference at **\~/Library/Application\ Support/com.proxyman.NSProxy/addons/libs/** ## 4. Notes > **Note:** Thanks to [Ivan Mathy](https://github.com/IvanMathy) for creating Boop app that facilitates Proxyman's built-in add-ons. --- Source: https://proxyman.com/docs/scripting/use-npm-install # Use npm install > Install npm packages such as dayjs or lodash into Proxyman's Application Support folder and use them in Proxyman Scripting with require(). ## Use npm Packages in Proxyman Scripting Proxyman Scripting supports `require()` for compatible npm packages installed in Proxyman's Application Support folder. This lets a script reuse popular JavaScript utilities instead of rewriting common logic by hand. This feature keeps the same `require()` keyword that Proxyman already uses for built-in libraries and user add-ons. Existing imports such as `@libs`, `@addons`, `@users`, JSON files, text files, and local files continue to work. ### Install a package Open Terminal and install packages into Proxyman's Application Support folder: * Install `dayjs` ```bash $ cd "$HOME/Library/Application Support/com.proxyman.NSProxy" $ npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund ``` After installation, the package should exist in: ``` ~/Library/Application Support/com.proxyman.NSProxy/node_modules ``` ### Use a package in a script Use the package name with `require()`: ```javascript const dayjs = require("dayjs"); async function onRequest(context, url, request) { const formattedDate = dayjs("2026-05-05T13:00:00Z").format("YYYY-MM-DD"); request.headers["X-Proxyman-Dayjs"] = formattedDate; return request; } ``` ### Examples #### Format a date with `dayjs` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const dayjs = require("dayjs"); async function onRequest(context, url, request) { request.headers["X-Request-Date"] = dayjs().format("YYYY-MM-DD"); return request; } ``` #### Normalize text with `lodash` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . lodash --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const _ = require("lodash"); async function onRequest(context, url, request) { const label = _.kebabCase("Hello Proxyman Scripts"); request.headers["X-Proxyman-Label"] = label; return request; } ``` #### Validate input with `validator` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . validator --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const validator = require("validator"); async function onRequest(context, url, request) { const email = new URL(url).searchParams.get("email") || ""; request.headers["X-Email-Is-Valid"] = validator.isEmail(email) ? "true" : "false"; return request; } ``` #### Create slugs with `slugify` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . slugify --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const slugify = require("slugify"); async function onRequest(context, url, request) { const title = new URL(url).searchParams.get("title") || "Hello Proxyman"; request.headers["X-Proxyman-Slug"] = slugify(title, { lower: true }); return request; } ``` #### Encode data with `js-base64` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . js-base64 --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const { Base64 } = require("js-base64"); async function onResponse(context, url, request, response) { response.headers["X-Proxyman-Encoded"] = Base64.encode("Proxyman"); return response; } ``` #### Decode HTML entities with `he` Install: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . he --ignore-scripts --no-audit --no-fund ``` Script: ```javascript const he = require("he"); async function onResponse(context, url, request, response) { response.headers["X-Decoded-Title"] = he.decode("Proxyman & Scripting"); return response; } ``` ### Compatibility Proxyman runs scripts with JavaScriptCore, not Node.js. npm packages work best when they are pure JavaScript and compatible with CommonJS. Supported: * CommonJS packages loaded with `require("package-name")` * Package entry points from `package.json` such as `main` and simple `exports` * Relative imports used inside installed packages, such as `require("./helper")` * JSON files required by packages Not supported: * Node.js built-in modules such as `fs`, `path`, `crypto`, `http`, or `child_process` * Native `.node` add-ons * Packages that require a full Node.js runtime * ESM-only packages that cannot be loaded with CommonJS `require()` ### Node.js native libraries Proxyman Scripting does not run inside the Node.js runtime. It only uses Node/npm as a package installation tool, then loads compatible JavaScript files with JavaScriptCore. Because of that, Node.js native libraries are not supported: * `require("fs")`, `require("path")`, `require("crypto")`, and other Node.js built-in modules are blocked. * `require("node:fs")` and built-in subpaths such as `require("fs/promises")` are blocked. * Native C/C++ add-ons compiled as `.node` files are blocked. * Packages that call Node-specific APIs such as `process.dlopen`, filesystem APIs, network sockets, or child processes will not work. Examples of packages that usually do not work in Proxyman Scripting: * `sharp` * `sqlite3` * `bcrypt` * `canvas` * `puppeteer` * packages that require `fs`, `path`, `crypto`, `http`, `https`, `net`, or `child_process` Use pure JavaScript packages or packages that provide a CommonJS browser-compatible build instead. ### Troubleshooting If `require("dayjs")` or another package returns `undefined`, check that the package is installed in the expected folder: ```bash ls "$HOME/Library/Application Support/com.proxyman.NSProxy/node_modules" ``` If `node_modules` is missing, install again with `--prefix .`: ```bash cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund ``` The `--prefix .` option is important because npm may otherwise walk up to a parent `package.json` and install packages outside Proxyman's folder. --- Source: https://proxyman.com/docs/scripting/write-your-own-addons # Write your own Addons > Write your own JavaScript addon for Proxyman Scripting, save it in the custom addons folder, and import it into any script with require(). ## 1. What's it? You can write your own addon to do what the built-in addons don't do yet. You can: * Write your own JavaScript addon. * Use [Built-in Libraries](https://proxyman.com/docs/scripting/built-in-js-libraries). * Write your library and share it with your colleagues. ## 2. How to write an addon? 1. Open the user addons folder at `~/Library/Application\ Support/com.proxyman.NSProxy/users`. Or, in the Script Editor, click **More** -> **Documentations** -> **Open Custom Addons Folder...** ![Proxyman Script Editor More menu with Documentations open and Open Custom Addons Folder highlighted](https://proxyman.com/docs/assets/proxyman-script-open-custom-addons-folder.jpg) _Open the Custom Addons folder_ 2\. Duplicate the `HelloWorld.js` file and rename it to **MyAwesomeAddon.js** 3\. Open the file to see the template. 4\. Change the metadata and write your JS Code ```javascript /** { "name":"My Awesome Addon", "description":"The first User Addons", "author":"Proxyman", "tags":"helloworld" } **/ const { md5 } = require("@addons/MD5.js"); const sayHello = () => { var content = "Hello World. My first custom Addon."; var hash = md5(content); return content + ". MD5 = " + hash; }; // Make sure you export the function at the end of method exports.sayHello = sayHello; ``` * You can import built-in addons with **require("@addons/\")** ```javascript const { md5 } = require("@addons/MD5.js"); ``` > **Note:** Check out the [built-in addons](https://proxyman.com/docs/scripting/addons#2-built-in-addons) that Proxyman provides * You can import a built-in library with **require("@libs/\")** > **Note:** Check out the [built-in library](https://proxyman.com/docs/scripting/built-in-js-libraries) that Proxyman provides 5\. Save the file 6\. Open your script in Proxyman and import the addon ```javascript // Import your addon // Make sure you import the functions that you export in the addon const { sayHello } = require("@users/MyAwesomeAddon.js"); // Usage sayHello(); ``` > **Note:** In **require("@users/MyAwesomeAddon.js")**, `@users` is the Custom Addons Folder. ## 3. Note > **Note:** Your own addons are stored at **\~/Library/Application\ Support/com.proxyman.NSProxy/users** > > This folder is safe. It's never overridden or removed by Proxyman. --- Source: https://proxyman.com/docs/scripting/snippet-code # Snippet Code > Copy ready-to-use JavaScript snippets for Proxyman Scripting: edit headers, queries, JSON bodies and status codes, map local files, call APIs, and more. ## 1. What's it? A collection of JavaScript snippets for the Proxyman Scripting Tool. > **Note:** Could not find the Snippet Code you are looking for? > > Please open a ticket on [GitHub](https://github.com/ProxymanApp/Proxyman) and we will help you ⭐️ > **Tip:** Use [Proxyman MCP](https://proxyman.com/docs/mcp) with your agent (Codex/Claude Code) to generate scripts easily 🚀 ## 2. Common on Request and Response * [Update Headers of Request or Response](https://proxyman.com/docs/scripting/snippet-code#http-header) * [Update Request Query](https://proxyman.com/docs/scripting/snippet-code#request-query) * [Update URLEncoded Form Request Body](https://proxyman.com/docs/scripting/snippet-code#urlencoded-form-body) * [Update JSON Request or Response Body](https://proxyman.com/docs/scripting/snippet-code#json-body) * [Map a local file to Response's Body like Map Local Tool](https://proxyman.com/docs/scripting/snippet-code#map-a-local-file-to-responses-body-like-map-local-tool-proxyman-2250) * [Change Request Scheme, Host, Port, Path](https://proxyman.com/docs/scripting/snippet-code#change-request-destination-scheme-host-port-path) * [Upstream ALPN and HTTP/2 settings](https://proxyman.com/docs/scripting/snippet-code#upstream-alpn-and-http2-settings) * [HTTP to HTTPS](https://proxyman.com/docs/scripting/snippet-code#http-to-https) * [HTTPS to HTTP](https://proxyman.com/docs/scripting/snippet-code#https-to-http) * [Change Request Method](https://proxyman.com/docs/scripting/snippet-code#change-http-request-method) * [Change Response Status Code](https://proxyman.com/docs/scripting/snippet-code#change-response-http-status-code) * [Logging](https://proxyman.com/docs/scripting/snippet-code#logging) * [Use JSON File as a Body of Request or Response](https://proxyman.com/docs/scripting/snippet-code#use-json-file-as-a-body-of-request-or-response) * [Use multiple JSON files](https://proxyman.com/docs/scripting/snippet-code#use-multiple-json-files) * [Local Map for GraphQL](https://proxyman.com/docs/scripting/snippet-code#map-local-with-graphql) * [Use ArrayBuffer in Request/Response Body](https://proxyman.com/docs/scripting/snippet-code#use-arraybuffer-in-requestresponse-body) * [Preserve the Host](https://proxyman.com/docs/scripting/snippet-code#preserve-the-host) * [Comment & Highlight with color](https://proxyman.com/docs/scripting/snippet-code#comment--highlight-with-color) * [Abort (close) the request/response connection (Like Block List Tool)](https://proxyman.com/docs/scripting/snippet-code#abort-the-requestresponse-like-block-list-tool) ### Multipart/form-data * [Read, add, update, or remove a part of multipart/form-data](https://proxyman.com/docs/scripting/snippet-code#multipartform-data-1) ## 3. Addons * [Base64 Encoding/Decoding or atob/btoa](https://proxyman.com/docs/scripting/snippet-code#use-base64-addon) * [Hashing Addon (MD5, SHA1, SHA256, SHA512)](https://proxyman.com/docs/scripting/snippet-code#use-hashing-addon-md5-sha1-sha256-sha512) * [UUIDv4 Generator](https://proxyman.com/docs/scripting/snippet-code#use-uuid-v4-addon) * [Deflate/Inflate or GZip/UnGZip](https://proxyman.com/docs/scripting/snippet-code#deflateinflate-and-gzipungzip) * [JWT Decode](https://proxyman.com/docs/scripting/snippet-code#jwt-decode) ## 3.1 Use \`npm install\` * [Use \`npm install dayjs\` to install 3rd-party npm packages](https://proxyman.com/docs/scripting/snippet-code#use-npm-install) ## 4. Regex * [Check if a given string contains only numbers](https://proxyman.com/docs/scripting/snippet-code#regex) * [Regex to get the Scheme, Host, Port, Path, and Query of the URL](https://proxyman.com/docs/scripting/snippet-code#regex-to-get-the-scheme-host-port-path-and-query-of-the-url) ## 5. Import / Export Files * [Import JSON File](https://proxyman.com/docs/scripting/snippet-code#json) * [Import Binary Data (Image)](https://proxyman.com/docs/scripting/snippet-code#binary-file) * [Import Text-based file (css, html, js....)](https://proxyman.com/docs/scripting/snippet-code#text-based-file) * [Import Files without using the "Import Tool"](https://proxyman.com/docs/scripting/snippet-code#import-file-without-using-the-import-tool) * [Write / Export to a local file](https://proxyman.com/docs/scripting/snippet-code#write--export-to-a-local-file) * [Check if a file exists](https://proxyman.com/docs/scripting/snippet-code#check-if-the-file-exists) * [Read a Local File](https://proxyman.com/docs/scripting/snippet-code#read-a-file) * [Use Response as Mock API](https://proxyman.com/docs/scripting/snippet-code#use-as-mock-api) ## 6. Miscellaneous * [By-pass CORS](https://proxyman.com/docs/scripting/snippet-code#by-pass-cors) * [Inject a Header to the Request or Response](https://proxyman.com/docs/scripting/snippet-code#inject-header-to-request--response) * [Response delay with sleep() function](https://proxyman.com/docs/scripting/snippet-code#response-delay-with-sleep-function) ## 7. Encryption/Decryption * [AES](https://proxyman.com/docs/scripting/snippet-code#aes-encryptiondecryption) * [DES](https://proxyman.com/docs/scripting/snippet-code#des-encryptiondecryption) ## 8. Map Remote with Scripting * [Map v1 to v2 Endpoints](https://proxyman.com/docs/scripting/snippet-code#map-v1-to-v2-endpoints) * [Map Localhost to Production](https://proxyman.com/docs/scripting/snippet-code#map-localhost-to-production) * [Map Production to Localhost](https://proxyman.com/docs/scripting/snippet-code#map-production-to-localhost) ## 9. Make Async/await HTTP Request (macOS) * [GET Request with Query](https://proxyman.com/docs/scripting/snippet-code#get-request-with-query) * [POST Request with JSON Body](https://proxyman.com/docs/scripting/snippet-code#post-request-with-json-body) * [POST Request with application/x-www-form-urlencoded](https://proxyman.com/docs/scripting/snippet-code#post-request-with-applicationx-www-form-urlencoded-body) * [PUT / PATCH / DELETE Request](https://proxyman.com/docs/scripting/snippet-code#put--patch--delete-request) ## 9.1. Make Async/await HTTP Request (Windows/Linux) * [Make a request with the Axios library](https://proxyman.com/docs/scripting/snippet-code#make-asyncawait-http-request-windowslinux) ## 10. URL and URLSearchParams * [URL and URLSearchParams](https://proxyman.com/docs/scripting/snippet-code#url-and-urlsearchparams) ## 11. Access Environment Variables * [Manually read system environment variables](https://proxyman.com/docs/scripting/snippet-code#reload-system-environment-variables) ## 12. Websocket * [Change the Websocket URL, Headers](https://proxyman.com/docs/scripting/snippet-code#change-websocket-url-requestsresponse-header) * [Log WebSocket messages with onWebsocket](https://proxyman.com/docs/scripting/snippet-code#log-websocket-messages-with-onwebsocket) * [Read text and JSON messages](https://proxyman.com/docs/scripting/snippet-code#read-text-and-json-messages) * [Inspect binary messages](https://proxyman.com/docs/scripting/snippet-code#inspect-binary-messages) * [Log ping and pong frames](https://proxyman.com/docs/scripting/snippet-code#log-ping-and-pong-frames) * [Inspect close frames](https://proxyman.com/docs/scripting/snippet-code#inspect-close-frames) * [Modify WebSocket messages with onWebsocket](https://proxyman.com/docs/scripting/snippet-code#modify-websocket-messages-with-onwebsocket) * [Change a field of JSON messages](https://proxyman.com/docs/scripting/snippet-code#change-a-field-of-json-messages) * [Replace text in both directions](https://proxyman.com/docs/scripting/snippet-code#replace-text-in-both-directions) * [Drop messages](https://proxyman.com/docs/scripting/snippet-code#drop-messages) * [Reply to a client message without the server](https://proxyman.com/docs/scripting/snippet-code#reply-to-a-client-message-without-the-server) * [Send a message to the server](https://proxyman.com/docs/scripting/snippet-code#send-a-message-to-the-server) * [Simulate a lost connection](https://proxyman.com/docs/scripting/snippet-code#simulate-a-lost-connection) * [Change a binary message](https://proxyman.com/docs/scripting/snippet-code#change-a-binary-message) ## HTTP Header ### Add/Update: Request or Response Header ```javascript function onRequest(context, url, request) { // Add or update Request Header request.headers["X-Proxyman-Key"] = "My-Value"; request.headers.name = "Proxyman"; return request; } function onResponse(context, url, request, response) { // Add or update Response Header response.headers["X-Proxyman-Key"] = "My-Value"; response.headers.id = 100; return response; } ``` ### Delete: Request or Response Header ```javascript function onRequest(context, url, request) { delete request.headers["X-Proxyman-Key"]; return request; } function onResponse(context, url, request, response) { delete response.headers["X-Proxyman-Key"]; return response; } ``` ## Request Query ### Add/Update ```javascript function onRequest(context, url, request) { request.queries["name"] = "Proxyman"; request.queries["platform"] = "macOS"; // => http://proxyman.io?name=Proxyman&platform=macOS return request; } ``` ### Delete ```javascript function onRequest(context, url, request) { delete request.queries["name"]; delete request.queries["platform"]; return request; } ``` ## URLEncoded Form Body ### Add/Update ```javascript function onRequest(context, url, request) { // Make sure the Request Header is application/x-www-form-urlencoded // Content-Type: application/x-www-form-urlencoded var formBody = request.body; formBody["name"] = "Proxyman"; formBody["platform"] = "macOS"; request.body = formBody; // => name=Proxyman&platform=macOS return request; } ``` ### Delete ```javascript function onRequest(context, url, request) { // Content-Type: application/x-www-form-urlencoded var formBody = request.body; delete formBody["name"]; delete formBody["platform"]; request.body = formBody; return request; } ``` ## Change Request Destination (scheme, host, port, path) ```javascript function onRequest(context, url, request) { request.scheme = "http"; request.host = "proxyman.dev"; request.port = 9090; request.path = "v1/data/user"; return request; } ``` ## Upstream ALPN and HTTP/2 settings Available in Proxyman v26.0.0 or later for macOS. See [HTTP/2](https://proxyman.com/docs/basic-features/http2) for setup. Set `request.upstream` in `onRequest` to change how Proxyman connects to the server. Enable SSL Proxying for the HTTPS domain. H2 overrides also require HTTP/2 enabled in Settings and an HTTP/2 client connection to Proxyman. ```javascript async function onRequest(context, url, request) { request.upstream = { tls: { alpnProtocols: ["h2"] }, http2: { headerTableSize: 65536, initialWindowSize: 6291456, maxHeaderListSize: 262144 } }; return request; } ``` ALPN accepts a nonempty list with no duplicates: * `["h2"]`: Require HTTP/2. Fail if the server cannot use it. * `["h2", "http/1.1"]`: Allow HTTP/1.1 fallback. * `["http/1.1"]`: Use HTTP/1.1. HTTP/2 values must be integers from `0` to the maximum below. Omitted or `null` fields use defaults. | Setting | Default | Maximum | | --- | --- | --- | | `headerTableSize` | `65536` | `4294967295` | | `initialWindowSize` | `6291456` | `2147483647` | | `maxHeaderListSize` | `262144` | `4294967295` | To reset all overrides, delete `request.upstream` or set it to `null`. Invalid or incompatible settings return a local `502` Scripting error. ## HTTP to HTTPS ```javascript function onRequest(context, url, request) { request.scheme = "https"; request.port = 443; // Don't forget to override the port return request; } ``` ## HTTPS to HTTP ```javascript function onRequest(context, url, request) { request.scheme = "http"; request.port = 80; // Don't forget to override the port return request; } ``` ## Change HTTP Request Method ```javascript function onRequest(context, url, request) { request.method = "POST"; return request; } ``` ## Change Response HTTP Status Code ```javascript function onResponse(context, url, request, response) { response.statusCode = 404; return response; } ``` ## JSON Body ### On Request ```javascript function onRequest(context, url, request) { // Set JSON content request.headers["Content-Type"] = "application/json"; // Get Request body var jsonBody = request.body; // Modify data jsonBody["name"] = "Proxyman"; jsonBody["platform"] = "macOS"; jsonBody["info"] = { "website": "proxyman.io", "region": "Earth" }; // Set it again request.body = jsonBody; return request; } ``` ### On Response ```javascript function onResponse(context, url, request, response) { // Set JSON content response.headers["Content-Type"] = "application/json"; // Get Request body var jsonBody = response.body; // Modify data jsonBody["name"] = "Proxyman"; jsonBody["platform"] = "macOS"; jsonBody["info"] = { "website": "proxyman.io", "region": "Earth" }; // Set it again response.body = jsonBody; return response; } ``` ### Multipart/form-data From Proxyman macOS 6.6.0 or later, you can read, add, delete a multipart/form-data ```javascript function onRequest(context, url, request) { // Only run for multipart requests if (!request.multipart) { return request; } var parts = request.multipart; // 1) List parts (debug) console.log("Multipart parts:", parts); // 2) Modify a text part by name for (var i = 0; i < parts.length; i++) { if (parts[i].name === "text_field") { var p = parts[i]; p.body = "Updated text from script"; parts[i] = p; } } // 3) Modify a file part by name (binary body as [UInt8]) for (var i = 0; i < parts.length; i++) { if (parts[i].name === "file_field") { var p = parts[i]; p.body = [72, 101, 108, 108, 111]; // "Hello" p.fileName = "hello.txt"; p.contentType = "text/plain"; parts[i] = p; } } // 4) Add a new text part parts.push({ name: "new_field", body: "Added by script" }); // 5) Remove a part by name var filtered = []; for (var i = 0; i < parts.length; i++) { if (parts[i].name !== "remove_me") { filtered.push(parts[i]); } } // Apply updates request.multipart = filtered; return request; } ``` ### Map a local file to Response's Body like Map Local Tool (Proxyman 2.25.0+) It's a convenient way to set a local file as the body with the `bodyFilePath` property. ```javascript // For request request.bodyFilePath = "~/Desktop/image.png"; // For response response.bodyFilePath = "~/Desktop/image.png"; ``` ```javascript function onResponse(context, url, request, response) { response.headers["Content-Type"] = "image/png"; response.bodyFilePath = "~/Desktop/image.png"; // Done return response; } ``` ```javascript function onResponse(context, url, request, response) { response.headers["Content-Type"] = "application/json"; response.bodyFilePath = "~/Desktop/my_response.json"; // Done return response; } ``` ### Use JSON File as a Body of Request or Response You can use a JSON file as the request or response body. Follow the [Import a JSON file](https://proxyman.com/docs/scripting/snippet-code#json) steps. ### Use multiple JSON files You can set a different body for each matching endpoint with an if statement. 1. Follow the [Import a JSON file](https://proxyman.com/docs/scripting/snippet-code#json) steps to import a JSON file into the script 2. Set Script Rule with wildcard or Regex pattern that can match many endpoints. E.g https://my-domain.com/v\* 3. Use \`includes()\` to check whether or not the endpoint is matched ```javascript const file_1 = require("@users/myfile_1.json"); const file_2 = require("@users/myfile_2.json"); const file_3 = require("@users/myfile_3.json"); function onResponse(context, url, request, response) { // Set JSON content response.headers["Content-Type"] = "application/json"; // Check if (url.includes("v1/data")) { response.body = file_1 } else if (url.includes("v2/login")) { response.body = file_2 } else if (url.includes("v3/user")) { response.body = file_3 } // Done return response; } ``` ### Map Local with GraphQL Read more at [https://github.com/ProxymanApp/Proxyman/issues/412#issuecomment-697101594](https://github.com/ProxymanApp/Proxyman/issues/412#issuecomment-697101594) ```javascript // Import your JSON file here const file = require("@users/B02D96D5.default_message_32E64A5B.json"); function onRequest(context, url, request) { // 1. Extract the queryName from the request var queryName = request.body.query.match(/\S+/gi)[1].split('(').shift(); // 2. Save to sharedState sharedState.queryName = queryName // Done return request; } function onResponse(context, url, request, response) { // 3. Check if it's the request we need to map if (sharedState.queryName == "user") { // 4. Import the local file by Action Button -> Import // Get the local JSON file and set it as a body (like Map Local) response.headers["Content-Type"] = "application/json"; response.body = file; } // Done return response; } ``` ### Use ArrayBuffer in Request/Response Body Since Javascript doesn't have the Data object type, the Data Body will convert to **Base64 Encoded String** in Javascript. To pass **Uint8Array**, **blob**, or **ArrayBuffer** to the body, make sure you convert to **Base64 Encoded String** and set the ContentType to `application/octet-stream` Proxyman will convert Base64 Encoding to ArrayBuffer, so the client will receive the data properly. ```javascript // Import const { btoa } = require('@addons/Base64.js'); function onResponse(context, url, request, response) { // Construct the ArrayBuffer const buffer = new ArrayBuffer(256) const view = new Uint8Array(buffer) for (let i = 0; i < view.length; i++) { view[i] = i } // Convert ArrayBuffer to Base64String var newBody = btoa(String.fromCharCode.apply(null, new Uint8Array(buffer))); // Set new body response.body = newBody; response.statusCode = 200 response.headers['Content-Type'] = 'application/octet-stream' // Done return response; } ``` ### Preserve the Host ```javascript function onRequest(context, url, request) { request.preserveHostHeader = true return request } ``` ### Comment & Highlight with color Use `comment` or `color` to highlight the flow in the main table view. ```javascript function onRequest(context, url, request) { request.comment = "It's a Request" request.color = "red" // red, blue, yellow, purple, gray, green return request } function onResponse(context, url, request, response) { response.comment = "It's a Response" response.color = "yellow" // red, blue, yellow, purple, gray, green return response } ``` ![Proxyman request list with highlighted rows, one strikethrough row, and notes in the Comment column](https://proxyman.com/docs/assets/proxyman-highlight-color-comment.jpg) _Rows with colors and comments_ ## Import Files with require() ### JSON 1. Prepare a JSON file and save it to your Desktop ```javascript // myfile.json { "name": "Proxyman", "platform": "macOS", "info": { "website": "proxyman.io", "region": "Earth" } } ``` 2\. Click **More** -> **Import JSON or Other File...**, then select your file ![Proxyman Script Editor More menu with Import JSON or Other File highlighted](https://proxyman.com/docs/assets/Screen%20Shot%202021-04-22%20at%2010.59.46.png) 3\. Proxyman will add the import code to the top of the script ```javascript // ~/Library/Application Support/com.proxyman.NSProxy/users/myfile.json const file = require("@users/myfile.json"); function onResponse(context, url, request, response) { // 1. Set header to JSON if need response.headers["Content-Type"] = "application/json"; // 2. Set Body as a imported file response.body = file; return response; } ``` > **Note:** The selected file is copied to **\~/Library/Application\ Support/com.proxyman.NSProxy/users** folder. > **Note:** For other file types, such as images, text, or PDF, make sure you set the correct **Content-Type header**. ### Binary File 1. Follow the same above instruction (Select your Binary File) 2. Set it as a body ```javascript // ~/Library/Application Support/com.proxyman.NSProxy/users/myscreenshot.png const file = require("@users/myscreenshot.png"); function onResponse(context, url, request, response) { // Set header response.headers["Content-Type"] = "image/png"; // Set Body response.body = file; return response; } ``` ### Text-Based File 1. Follow the same above instruction (Select your text file) 2. Set it as a body ```javascript // ~/Library/Application Support/com.proxyman.NSProxy/users/main.css const file = require("@users/main.css"); function onResponse(context, url, request, response) { // Set header response.headers["Content-Type"] = "text/css"; // Set Body response.body = file; return response; } ``` ### Import File without using the "Import Tool" From Proxyman 2.24.0+, you can import any file without using the "Import Tool". ```javascript // Import your file from your Desktop folder const file = require("~/Desktop/myfile.json"); function onResponse(context, url, request, response) { // 1. Set header to JSON if need response.headers["Content-Type"] = "application/json"; // 2. Set Body as a imported file response.body = file; return response; } ``` * If the file has ".js" as an extension => Proxyman will execute it as a JS Script * Otherwise, Proxyman will import it as normal > **Note:** Only files imported with the "Import Tool" are included when you export the script to a colleague. ### Use as Mock API You can use Scripting as a Mock API. See [Use Scripting as a Mock API](https://proxyman.com/docs/scripting/script#8-use-scripting-as-a-mock-api). ## Using Addons [Full list of built-in addons](https://proxyman.com/docs/scripting/addons) ### Use Base64 Addon ```javascript // Encode Base64 const { btoa } = require("@addons/Base64.js") // Usage: var text = "HelloWorld"; var encodedText = btoa(text); ``` ```javascript // Decode Base64 const { atob } = require("@addons/Base64.js") // Usage: var text = atob("aGVsbG8="); ``` ### Use Hashing Addon (MD5, SHA1, SHA256, SHA512) ```javascript // Hash MD5 const { md5 } = require("@addons/MD5.js") // Usage: var hashedText = md5("Hello World"); ``` ```javascript // Hash SHA1 const { sha1 } = require("@addons/SHA1.js") // Usage: var hashedText = sha1("Hello World"); ``` ### Use UUID-v4 Addon ```javascript // Generate UUID v4 const { uuidv4 } = require("@addons/UUID.js") // Usage: var uuid = uuidv4(); ``` ## Deflate/Inflate and GZip/UnGZip ### Deflate/inflate ```javascript const { inflate, deflate } = require("@addons/Pako.js") // Compress var input = "Hello World from Pako!!!" var result = deflate(input); console.log(result); // eJzzSM3JyVcIzy/KSVFIK8rPVQhIzM5XVFQEAGsMB/8= // Decompress var text = 'eJzzSM3JyVcIzy/KSVFIK8rPVQhIzM5XVFQEAGsMB/8='; var rawText = inflate(text); console.log(rawText); // Hello World from Pako!!! ``` ### GZip/UnGZip ```javascript const { ungzip, gzip } = require("@addons/Pako.js") // Compress var text = 'HelloWorld'; var result = gzip(text); console.log(result); // H4sIAAAAAAAAA/NIzcnJD88vykkBAHkMd3cKAAAA // Decompress var text = 'H4sIAAAAAAAAA/NIzcnJD88vykkBAHkMd3cKAAAA'; var rawText = ungzip(text); console.log(rawText); // HelloWorld ``` ### JWT Decode ```javascript const { jwtDecode } = require('@addons/JWTDecode.js'); var text = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'; var jSONObject = jwtDecode(text) ``` ## Logging ```javascript // Print the obj const myObj = {}; console.log(myObj); // Print type of the obj console.log(typeof(myObj)); ``` ## Regex ### Only number ```javascript //Init Regex var reg = /^-?\d*\.?\d*$/; if (reg.test("123123123")) { console.log("Matched"); } ``` ### Regex to get the Scheme, Host, Port, Path, and Query of the URL ```javascript function onRequest(context, url, request) { console.log(url); // Get each part const regex = /^(https?):\/\/([^:\/\n]+)(?::(\d+))?([^#\n?]+)(?:\?([^#\n]+))?/; const [, scheme, host, port, path, query] = url.match(regex); // Assign again request.scheme = scheme; request.host = host; if (port !== undefined) { request.port = parseInt(port); } request.path = path; // Log console.log("----------"); console.log(scheme); console.log(host); console.log(port); console.log(path); // Done return request; } ``` ## Miscellaneous ### By-pass CORS ```javascript function onResponse(context, url, request, response) { // Allow all response.headers["Access-Control-Allow-Origin"] = "*"; response.headers["Access-Control-Allow-Headers"] = "*"; response.headers["Access-Control-Allow-Methods"] = "*"; // Done return response; } ``` ### Inject Header to Request / Response ```javascript function onRequest(context, url, request) { // add header request.headers["My-Injected-Header"] = "Proxyman"; return request } function onResponse(context, url, request, response) { // add header response.headers["My-Injected-Header"] = "Proxyman"; return response; } ``` ### Response delay with sleep() function It's useful for simulating a "Slow Network" on a particular request or response. For a GUI tool, check out [Network Conditions](https://proxyman.com/docs/advanced-features/network-throttling#1-whats-it). * macOS ```javascript function onResponse(context, url, request, response) { console.log("Start sleep"); // Sleep 5 seconds sleep(5000); // Done return response; } ``` * Windows/Linux ```javascript async function onResponse(context, url, request, response) { console.log("Start sleep"); // Sleep 5 seconds // Must use `await` keyword on Windows/Linux await sleep(5000); // Done return response; } ``` ### AES Encryption/Decryption ```javascript const { encryptAES, decryptAES } = require("@addons/CryptoJS.js") function onRequest(context, url, request) { // Encrypt var message = 'my message from Proxyman'; var password = 'secret key 123'; var ciphertext = encryptAES(message, password); // Decrypt var originalText = decryptAES(ciphertext, password); // Done return request; } ``` ### DES Encryption/Decryption ```javascript const { encryptDES, decryptDES } = require("@addons/CryptoJS.js") function onRequest(context, url, request) { // Encrypt var message = 'my message from Proxyman'; var password = 'secret key 123'; var ciphertext = encryptDES(message, password); // Decrypt var originalText = decryptDES(ciphertext, password); // Done return request; } ``` ### Write / Export to a local file * Override Mode ```javascript function onResponse(context, url, request, response) { // Write to single file writeToFile(response.body, "~/Desktop/body.json"); // Write the Body to file with flow ID writeToFile(response.body, "~/Desktop/sample-" + context.flow.id); // Done return response; } ``` * Append Mode (Only for Proxyman 3.6.2+) ```javascript async function onResponse(context, url, request, response) { // Append to the existed file // Or create a new file if it doesn't exist var opt = {appendFile: true} writeToFile(response.body, "~/Desktop/body.json", opt); // Done return response; } ``` ### Check if the file exists * Available: Proxyman macOS 5.4.0+ ```javascript async function onRequest(context, url, request) { const filePath = "~/Desktop/myfile.json" // check if the file exists if (isFileExists(filePath)) { console.log("File exists"); } else { console.log("File NOT exists"); } // Done return request; } ``` ### Read a file * If it's text-based -> Return a **String** * Otherwise -> Return **Uint8Array** * Available: Proxyman macOS 5.4.0+ ```javascript async function onRequest(context, url, request) { // console.log(request); const textFilePath = "~/Desktop/myfile.json"; // check exist if (isFileExists(textFilePath)) { // read from file const text = readFromFile(textFilePath); // parse string to JSON Object const obj = JSON.parse(text); } // Read binary file const binaryFilePath = "~/Desktop/screenshot.png"; const binaryFile = readFromFile(binaryFilePath); // Uint8Array // Done return request; } ``` ## Map Remotes ### Map v1 to v2 endpoints ```javascript function onRequest(context, url, request) { // Replace v1 to v2 in URL Path var newPath = request.path.replace("v1", "v2"); request.path = newPath // Done return request; } ``` ### Map localhost to production ```javascript function onRequest(context, url, request) { // Use production URL request.scheme = "https"; request.host = "proxyman.io"; request.port = 443; // Done return request; } ``` ### Map production to localhost ```javascript function onRequest(context, url, request) { // Use localhost URL request.scheme = "http"; request.host = "localhost"; request.port = 3000; // Done return request; } ``` ## Make async/await HTTP Request (macOS) > **Note:** \`$http\` is available on macOS. For Windows/Linux, see the next section. ### GET Request with Query ```javascript async function onResponse(context, url, request, response) { // GET Request with Query var url = "https://httpbin.proxyman.app/get?id=proxyman&country=united%20states"; var output = await $http.get(url); // Get Status Code console.log(output.statusCode); // Get body console.log(output.body) // Get header console.log(output.headers) // Done return response; } ``` ### POST Request with JSON Body ```javascript async function onResponse(context, url, request, response) { // Define JSON Body and Header // Make sure "Content-Type" is "application/json" var param = { body: { "user": { "name": "Proxyman" } }, headers: { "Content-Type": "application/json" } } // POST request with await var output = await $http.post("https://httpbin.proxyman.app/post", param); // Get Status Code console.log(output.statusCode); // Get body console.log(output.body) // Get header console.log(output.headers) // Done return response; } ``` ### POST Request with application/x-www-form-urlencoded body ```javascript async function onResponse(context, url, request, response) { // Define form Body and Header // Make sure "Content-Type" is "application/x-www-form-urlencoded" var param = { body: { "key1": "value1", "key2": "value2" }, headers: { "Content-Type": "application/x-www-form-urlencoded" } } // POST request with await var output = await $http.post("https://httpbin.proxyman.app/post", param); // Get Status Code console.log(output.statusCode); // Get body console.log(output.body) // Get header console.log(output.headers) // Done return response; } ``` ### PUT / PATCH / DELETE Request ```javascript async function onRequest(context, url, request) { var param = { body: { "user": { "name": "Proxyman" } }, headers: { "Content-Type": "application/json" } } var output = await $http.post("https://httpbin.proxyman.app/post", param); var output = await $http.put("https://httpbin.proxyman.app/put", param); var output = await $http.delete("https://httpbin.proxyman.app/delete", param); // Done return request; } ``` ## Make async/await HTTP Request (Windows/Linux) Windows/Linux ships with a built-in [Axios](https://github.com/axios/axios) library. You can easily make HTTP(s) requests with \`Axios\` syntax. ```javascript async function getUser() { try { const response = await axios.get('https://httpbin.proxyman.app/user?ID=12345'); console.log(response); } catch (error) { console.error(error); } } ``` ## Abort the request/response like Block List Tool * Only available for Proxyman 3.11.0 and later ### Abort the request ```javascript function onRequest(context, url, request) { // drop the connection abort(); } ``` ```javascript function onRequest(context, url, request) { // Use the if to abort on certain conditions if (true) { abort(); return; // Must return a void to stop the func } // Done return request; } ``` ### Abort the response ```javascript function onResponse(context, url, request, response) { // drop the connection abort(); } ``` ## URL and URLSearchParams From Proxyman 4.13.0 or later, [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) and [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) are natively supported. ```javascript function onRequest(context, url, request) { // URL const urlObj = new URL("https://proxyman.io/api/v1/user?id=123"); console.log(urlObj.hostname); console.log(urlObj.search); console.log(urlObj.searchParams); // URLSearchParams const params1 = new URLSearchParams("foo=1&bar=2"); // Done return request; } ``` ## Reload System Environment Variables Proxyman macOS 4.15.0 or later. Enable the permission first: **More** button -> **Environment Variables** -> **Allow all scripts to access Environment Variables**. ```javascript async function onRequest(context, url, request) { // manually reload to get the latest changes _reloadEnv(); // get env console.log($PROXYMAN_ID) // Done return request; } ``` ## Change Websocket URL, Requests/Response Header * Supported from Proxyman 6.2.0 or later for macOS. * `onRequest` and `onResponse` modify the URL and handshake headers. To read the messages, use [onWebsocket](https://proxyman.com/docs/scripting/snippet-code#log-websocket-messages-with-onwebsocket) (Proxyman 26.1.0 or later for macOS, Windows and Linux). To change them, use [Modify WebSocket Messages](https://proxyman.com/docs/scripting/snippet-code#modify-websocket-messages-with-onwebsocket) (macOS Proxyman 26.2.0 or later, Windows/Linux Proxyman 26.1.0 or later). **Map from localhost to production** * Rule ws://proxyman.debug:3000 ```js async function onRequest(context, url, request) { // console.log(request); console.log(url); request.scheme = "wss"; request.host = "wss.httpbin-proxyman.xyz" request.port = 443 // Done return request; } ``` **Production to localhost** * Rule wss://echo.websocket.org ```js async function onRequest(context, url, request) { // console.log(request); console.log(url); request.scheme = "ws"; request.host = "proxyman.debug" request.port = 3000 // Done return request; } ``` ## Log WebSocket messages with onWebsocket > **Warning:** These `onWebsocket` snippets require **Proxyman 26.1.0 or later for macOS, Windows and Linux**. They are not available on iOS. Match the captured `ws://` or `wss://` URL, save and activate the script, then reconnect the WebSocket. See [Scripting with WebSocket](https://proxyman.com/docs/scripting/script#41-scripting-with-websocket) for setup and the complete `message` object. Each example defines a separate `onWebsocket` function. Use one example, or combine the checks into a single function. Without the **Modify WebSocket Messages** option, the hook is read-only: changing `message` or returning a value does not modify traffic. To change messages, see [Modify WebSocket messages with onWebsocket](https://proxyman.com/docs/scripting/snippet-code#modify-websocket-messages-with-onwebsocket). Log every captured message from both sides: ```javascript function onWebsocket(context, url, request, response, message) { console.log(`[${message.from}] ${message.type}: ${message.data}`); } ``` ### Read text and JSON messages Inspect text sent by the server. JSON messages are parsed when valid; other text is logged unchanged. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type !== "text" || message.from !== "server") return; try { const payload = JSON.parse(message.data); console.log("Server JSON: " + JSON.stringify(payload, null, 2)); } catch (error) { // A text message does not have to contain JSON. console.log("Server text: " + message.data); } } ``` Proxyman reassembles fragmented text frames before calling the hook, so you can parse the complete JSON message here. Binary fragments are also reassembled; there is no separate continuation-frame callback. ### Inspect binary messages Use `message.rawData` for the original bytes. `message.data` is only a text representation and may be `Binary (length=N)`. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type !== "binary") return; const bytes = message.rawData; // Limit the preview so large messages do not flood the console. const hex = Array.from(bytes.slice(0, 32)) .map(byte => byte.toString(16).padStart(2, "0")) .join(" "); const suffix = bytes.length > 32 ? " ..." : ""; console.log(`[${message.from}] binary (${bytes.length} bytes): ${hex}${suffix}`); } ``` `rawData` is a copied `Uint8Array` and is non-enumerable. Access it directly rather than expecting `console.log(message)` or `JSON.stringify(message)` to include it. ### Log ping and pong frames Use these events to inspect heartbeat traffic in either direction. Ping and pong payloads are not exposed. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type !== "ping" && message.type !== "pong") return; console.log(`[${message.from}] ${message.type} on ${url}`); } ``` ### Inspect close frames Log the close code and which side sent the frame. The close reason is not exposed. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type !== "close") return; console.log(`[${message.from}] closed with code ${message.closeCode}`); } ``` ## Modify WebSocket messages with onWebsocket > **Warning:** These snippets require **macOS Proxyman 26.2.0 or later** or **Windows/Linux Proxyman 26.1.0 or later**. They are not available on iOS. Check **Modify WebSocket Messages** on the rule, keep **Request** checked, save and activate the script, then reconnect the WebSocket. See [Modify WebSocket Messages](https://proxyman.com/docs/scripting/modify-websocket-messages) for the setup and what each return value does: * `return message`: send the message, with your changes. * `return null`: drop the message. * No return: send the original message. * `sendToClient(data)` / `sendToServer(data)`: send a new message. A String sends a text message, a `Uint8Array` a binary message. * `abort()`: close the WebSocket on both sides. ### Change a field of JSON messages Change a field of every JSON message from the server. Other messages are sent as they are. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type !== "text" || message.from !== "server") { return message; } try { const json = JSON.parse(message.data); if (json.type === "price") { json.price = 0; message.data = JSON.stringify(json); } } catch (error) { // Not JSON: send it as it is } return message; } ``` ### Replace text in both directions Switch a host name in every text message, from the client and from the server. ```javascript const FIND_REGEX = /staging\.example\.com/g; const REPLACE_WITH = "api.example.com"; function onWebsocket(context, url, request, response, message) { if (message.type === "text") { message.data = message.data.replace(FIND_REGEX, REPLACE_WITH); } return message; } ``` ### Drop messages Drop the client messages that match a regex, for example analytics events. The server never sees them. ```javascript const DROP_REGEX = /"type"\s*:\s*"analytics"/; function onWebsocket(context, url, request, response, message) { if (message.from === "client" && message.type === "text" && DROP_REGEX.test(message.data)) { console.log("Dropped: " + message.data); return null; } return message; } ``` ### Reply to a client message without the server Answer a message of the client with `sendToClient()`, and drop the original so the server never sees it. Useful to mock a server reply. ```javascript function onWebsocket(context, url, request, response, message) { if (message.from === "client" && message.type === "text" && message.data.includes('"subscribe"')) { sendToClient(JSON.stringify({ type: "error", code: 503, text: "Service unavailable" })); return null; } return message; } ``` Messages sent with `sendToClient()` and `sendToServer()` don't run `onWebsocket()` again, so the script can't loop forever. ### Send a message to the server Send an extra message to the server when the client sends its first message, for example to subscribe to another channel. ```javascript let isSubscribed = false; function onWebsocket(context, url, request, response, message) { if (message.from === "client" && message.type === "text" && !isSubscribed) { isSubscribed = true; sendToServer(JSON.stringify({ type: "subscribe", channel: "ETH" })); } return message; } ``` The code outside `onWebsocket()` runs once per connection, so `isSubscribed` starts at `false` for every new connection. ### Simulate a lost connection Close the WebSocket on both sides after 10 messages, to test how your app reconnects. ```javascript const CLOSE_AFTER_MESSAGES = 10; let messageCount = 0; function onWebsocket(context, url, request, response, message) { messageCount += 1; if (messageCount === CLOSE_AFTER_MESSAGES) { console.log("Closing the WebSocket after " + messageCount + " messages"); abort(); } return message; } ``` ### Change a binary message Set new bytes with a `Uint8Array`. A message keeps its type: a binary message stays binary. ```javascript function onWebsocket(context, url, request, response, message) { if (message.type === "binary" && message.from === "server") { message.rawData = new Uint8Array([1, 2, 3]); } return message; } ``` ## Use \`npm install\` Read more at [use-npm-install.md](https://proxyman.com/docs/scripting/use-npm-install) ### Install a package Open Terminal and install packages into Proxyman's Application Support folder: * Install `dayjs` ```bash $ cd "$HOME/Library/Application Support/com.proxyman.NSProxy" $ npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund ``` After installation, the package should exist in: ``` ~/Library/Application Support/com.proxyman.NSProxy/node_modules ``` ### Use a package in a script Use the package name with `require()`: ```javascript const dayjs = require("dayjs"); async function onRequest(context, url, request) { const formattedDate = dayjs("2026-05-05T13:00:00Z").format("YYYY-MM-DD"); request.headers["X-Proxyman-Dayjs"] = formattedDate; return request; } ``` --- Source: https://proxyman.com/docs/scripting/environment-variables # Environment Variables > Share data between Proxyman scripts with sharedState, and read system environment variables such as API tokens in your scripts with the $ prefix. ## 1. Shared State > **Note:** Shared State works on all macOS versions that Proxyman supports (**macOS 14 Sonoma or later**). You can share state between **onRequest()** and **onResponse()**, and between **different scripts**, with the global object **sharedState**. * **sharedState** is a JS Object (Dictionary). You can assign any keys and values in **onRequest()**, then read the data in **onResponse()** or in **different scripts**. The following code shows how to: * Get the global counter and increase it each time the script runs * Share data between Request and Response ```javascript function onRequest(context, url, request) { // Save some state to sharedState sharedState.url = url; sharedState.data = "custom"; sharedState.info = {"username": "Proxyman"}; // Increase the global counter var count = sharedState.count ?? 0; count += 1; sharedState.count = count; // Log console.log(sharedState); return request; } function onResponse(context, url, request, response) { // Receive it console.log("Custom data = " + sharedState.data); console.log("sharedState.count = " + sharedState.count); // Done return response; } ``` > **Note:** From Proxyman 2.25.0+, **sharedState** is available across different scripts. It is only released when you quit Proxyman or call the \`clearSharedState()\` function. > **Note:** Before Proxyman 2.24.0, **sharedState** only lives in the current flow that runs the script, and it's released when the script finishes. To clear all data, use the \`clearSharedState()\` function. ```javascript // Clear all data from sharedState object clearSharedState(); ``` ## 2. Environment Variables The Environment Variables feature is available from **Proxyman 3.8.0** or later. * Scripts can read system environment variables. * Supports bash and zsh. ### How to use 1. Define an env in your `~/.zshrc` or `~/.bashrc` ```bash export ACCESS_TOKEN=AAABBBCCC export PROXYMAN_PATH=/Users/my_user/Desktop/file-mapper ``` 2\. Open any script -> **More** button -> **Environment Variables** -> **Allow all scripts to access Environment Variables**. 3\. Click **Reload** to load the latest env changes. ![Proxyman Script Editor More menu with Environment Variables open: Allow all scripts to access Environment Variables, Reload](https://proxyman.com/docs/assets/proxyman-script-environment-variables-menu.jpg) _Allow scripts to read Environment Variables_ 4\. Access an env variable in your script with the `$` prefix ```javascript async function onResponse(context, url, request, response) { console.log($PATH); console.log($ACCESS_TOKEN); console.log($PROXYMAN_PATH); // Done return response; } ``` ## 3. Additions * Manually reload the system env (Proxyman macOS 4.15.0 or later). Enable the permission first: **More** button -> **Environment Variables** -> **Allow all scripts to access Environment Variables**. ```javascript async function onRequest(context, url, request) { // manually reload to get the latest changes _reloadEnv(); // get env console.log($PROXYMAN_ID) // Done return request; } ``` --- Source: https://proxyman.com/docs/troubleshooting/proxyman-does-not-work-with-vpn-apps # Proxyman does not work with VPN apps > Proxyman not capturing traffic while a VPN is on? See which VPN apps work with Proxyman, and how to set the HTTP proxy for FortiClient, AnyConnect and more. In general, VPN apps can conflict with all web debugging proxy apps, including Proxyman, Charles Proxy, Fiddler, and Wireshark. This page lists which VPN apps work and do not work with Proxyman, and how to fix them. ## Problems Proxyman cannot capture any HTTP/HTTPS traffic when you're using corporate VPNs. > **Note:** If your VPN changes the system proxy or an app on your Mac ignores it, try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension). Capture works independently of the system proxy, but VPN compatibility can vary. HTTPS still needs certificate trust and [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying). > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## How to fix it in general The VPN app sends all traffic through the VPN server instead of the Proxyman local server (127.0.0.1:9090). Therefore, Proxyman cannot capture the traffic. To fix it: * Open your VPN's settings and look for a field where you can set the HTTP/HTTPS proxy. * If it's available, set it to the address **127.0.0.1** and port **9090**. * If it's not available, search for "\ config HTTP Proxy" to see how to do it. Then, Proxyman can capture traffic while your VPN app is on. ## ✅ New Solution for iOS: Atlantis + Proxyman * Works with any VPN. * Capture all HTTP/HTTPS or WebSocket traffic from your iOS app. * No need to set up a proxy or install any certificate. * Works with iOS Simulators and iOS physical devices. ### 👉 How to use Atlantis? * Check out the [Atlantis README](https://github.com/ProxymanApp/atlantis) * Blog: [How to capture HTTPS traffic from an iOS app with a company VPN](https://proxyman.com/posts/capture-https-ios-app-with-company-vpn) ## List of VPNs that work with Proxyman/CharlesProxy/Fiddler ### 1. Tunnelblick Works fine without any configuration. ### 2. FortiClient Works fine if you set the HTTP proxy to Proxyman. Follow the [FortiClient proxy settings guide](https://docs.fortinet.com/document/forticlient/6.2.0/xml-reference-guide/179671/proxy-settings). ### 3. AnyConnect * Try to set the HTTP proxy if it's available in AnyConnect's preferences. * Add your VPN host to the bypass list in Proxyman: **Tools** -> **Proxy Settings** -> **Bypass Proxy Settings…**. You can also find the list in System Settings -> Network -> Wi-Fi -> Details… -> Proxies -> "Bypass proxy settings for these hosts & domains". (Ref: [GitHub issue #264](https://github.com/ProxymanApp/Proxyman/issues/264#issuecomment-816093447)) ### 4. Pulse Secure and Global Protect VPN **Solution 1:** First, you need to install [OpenConnect](https://casper.infradead.org/openconnect/index.html). ```bash brew install openconnect ``` Get the installation path for `openconnect`: ``` whereis -b openconnect ``` After that, edit `/etc/sudoers`: ``` sudo visudo -f /etc/sudoers ``` Add this line and replace `` with your binary path. ``` %admin ALL=(ALL) NOPASSWD: ``` Now, you can connect to your secured proxy using the Juniper SSL / Pulse Connect Secure protocol. ``` sudo openconnect --protocol nc -u ``` Once connected, launch Proxyman. It should capture traffic as usual. Credit: @florentmorin, from [GitHub issue #1203](https://github.com/ProxymanApp/Proxyman/issues/1203) > **Note:** Please consult with your Security Team before using the **sudo** command. **Solution 2:** It might work if you follow these steps: 1. Connect to the VPN and verify it works. 2. Open the Proxyman app. 3. Reset the VPN connection. Credit: @AddictiveColors ### 5. **Viscosity** 1. Follow the documentation to [override the HTTP/HTTPS proxy](https://www.sparklabs.com/support/kb/article/advanced-configuration-commands/#proxy-http) in the Viscosity VPN app. Sample configuration: ``` #viscosity proxy-http localhost 9090 #viscosity proxy-https localhost 9090 ``` Alternative solution for Viscosity VPN: 1. Open the **Advanced** tab in the connection settings and add these lines: ``` dhcp-option HTTPPROXY 127.0.0.1:9090 dhcp-option HTTPSPROXY 127.0.0.1:9090 ``` 2. Start Proxyman. Done. Reference: [Stack Overflow answer about Charles and VPN](https://stackoverflow.com/a/42515317/3127477) ### 6. Cisco VPN 1. Disconnect your VPN. 2. Open Proxyman. 3. Go to **Tools** -> **Proxy Settings** -> **Bypass Proxy Settings…** 4. Add your VPN server domain (for example, vpn.yourcompany.com) and click **Done**. 5. Connect your VPN again. Reference: [GitHub issue #264](https://github.com/ProxymanApp/Proxyman/issues/264#issuecomment-2317101771) ### 7. Nord VPN * For NordVPN, you can use the project below to set up a local HTTP/HTTPS proxy that routes through NordVPN. Then use that proxy server as an [External Proxy](https://proxyman.com/docs/advanced-features/external-proxy) in Proxyman. * [nordlynx-proxy on GitHub](https://github.com/edgd1er/nordlynx-proxy) Credit to @seidnerj from [GitHub issue #264](https://github.com/ProxymanApp/Proxyman/issues/264#issuecomment-2416373960) ### 8. Zscaler Follow this [workaround from the Zscaler team](https://github.com/ProxymanApp/Proxyman/issues/1307#issuecomment-1236202303). ## List of VPNs that do not work with Proxyman/CharlesProxy/Fiddler ### 1. Sophos Sophos doesn't work with any web debugging proxy app. It's a known issue from Sophos and there is no fix for it. Ask your Security team to set the HTTP/HTTPS proxy in Sophos. Update: **Sophos 10.0.4** (A/V Endpoint Protection) might work with Proxyman with a new network proxy extension, but it has a known issue that causes high CPU spikes. Sophos planned to fix it in an upcoming EAP release. Credit: @AddictiveColors --- Source: https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy # My Remote Devices (iOS/Android) could not connect to Proxyman? > iPhone or Android has no internet after setting the Wi-Fi proxy, or can't open proxy.man/ssl? Check the IP, port, VPN and firewall to connect to Proxyman. ## **1.** Problems * ❌ My iOS or Android device can't access the internet after I change the proxy setting in the Wi-Fi settings. * ❌ I can't download the certificate from **http://cert.proxyman.io** or **http://proxy.man/ssl** > **Note:** For Android, follow the [Android Devices and Android Emulators](https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy#android-devices-and-android-emulators) section. ## 2. Solution: iOS devices Double-check the following steps: ### 0. Issue with iOS 16 Physical Devices / Simulator Some users report that **Proxyman** and **Charles Proxy** could not capture any traffic from iOS 16 devices or simulators, even though the HTTP proxy is set. It's an iOS bug. If you see it on iOS 17, iOS 18 or iOS 26, use the same fix. Workarounds: #### iOS physical devices * Forget the Wi-Fi network, connect again, and set the HTTP proxy again. * Use the [Atlantis framework](https://github.com/ProxymanApp/atlantis) to capture the traffic. #### iOS Simulator * Follow the [iOS Simulator setup guide](https://proxyman.com/docs/debug-devices/ios-simulator). * Use the [Atlantis framework](https://github.com/ProxymanApp/atlantis) to capture the traffic. - [iOS 16 and iOS 17 issues](https://proxyman.com/docs/troubleshooting/ios-16-devices-issues) ### 1. Make sure your Mac device and iOS/Android devices are on the same network If they're on different networks, they can't connect to each other. ### 2. Make sure the server IP and port match Proxyman ![iOS Configure Proxy screen set to Manual with server 192.168.0.101 and port 9090](https://proxyman.com/docs/assets/IMG_4110.png) _Proxy settings on the iPhone_ ![Proxyman iOS Setup Guide with Wi-Fi proxy server 192.168.64.4, port 9090 and certificate install steps](https://proxyman.com/docs/assets/proxyman-ios-setup-guide.jpg) _Server IP and port in the iOS Setup Guide_ ### 3. Turn OFF all VPN apps on macOS and iOS/Android devices By default, a VPN app **forces** all traffic through the VPN server instead of the Proxyman proxy server (port 9090). Therefore, no requests appear in Proxyman. Turning OFF all VPN apps will fix it: * For **iOS** devices: Open Settings -> General -> VPN & Device Management -> VPN and make sure the VPN status is **Not Connected**. * For **Android** devices: Find the VPN setting in the Settings app and turn it OFF. * For **macOS**: Quit all VPN apps. If you can't turn off your VPN, see [Proxyman does not work with VPN apps](https://proxyman.com/docs/troubleshooting/proxyman-does-not-work-with-vpn-apps). ### 4. Firewall settings (macOS) The macOS firewall might block incoming connections to your Mac. Then your remote devices can't connect to Proxyman. On **macOS**: Open **System Settings -> Network -> Firewall -> Options…** **Verify that:** * Block all incoming connections is **OFF** * The Proxyman app is set to **Allow incoming connections** * If Proxyman is not in the list, add it with the **+** button * Automatically allow built-in software to receive incoming connections is **ON** * Automatically allow downloaded signed software to receive incoming connections is **ON** ### 5. Firewall settings (Windows 10/11) Windows 10/11 might block Proxyman, so iPhone and Android devices can't connect to the app. To fix it: 1. Search for and open the "Windows Defender Firewall" app, then click "Advanced settings" on the left panel. 2. Select "Inbound Rules". 3. Find proxyman.exe and double-click it to open its settings. 4. Select "Allow the connection" in the General tab. 5. Click OK. ![Windows Defender Firewall inbound rule for proxyman.exe set to Allow the connection](https://proxyman.com/docs/assets/CleanShot%202023-01-05%20at%2009.26.50%402x.png) _Allow Proxyman in Windows Firewall_ ### 6. If you're on a company network, ask the Security team to open Proxyman's port 9090 Some companies block certain ports by default. Then your iOS devices can't reach Proxyman on port 9090. ### 7. Use a Private tab in Safari to open http://cert.proxyman.io or http://proxy.man/ssl ### 8. I'm still unable to connect If you followed all the steps above and the configuration is correct, but it still doesn't work: Try to **turn Wi-Fi off and on, forget the Wi-Fi network (iOS),** and **restart your computer**. ### 9. Still doesn't work? (iOS app only) Setting the HTTP proxy by hand and installing and trusting the Proxyman certificate on iOS devices is hard. We understand that. Try Atlantis, an iOS framework that does it for you. - [Atlantis for iOS](https://proxyman.com/docs/atlantis/atlantis-for-ios) ## Android Devices and Android Emulators ### 1. After setting the HTTP proxy in the Wi-Fi settings, I can't open http://proxy.man/ssl * [Follow the troubleshooting steps above](https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy#1-make-sure-your-mac-device-and-iosandroid-devices-are-on-the-same-network) ☝️ * Double-check the Wi-Fi connection in the emulator. It must show Connected (not Limited Connection or No Internet). If it doesn't, **forget the network** and **reconnect to the Wi-Fi.** ### 2. Install and trust the Proxyman CA on Android API 30+ From Android Emulator API 30+, you need extra steps to trust the Proxyman certificate: * Open http://proxy.man/ssl in Google Chrome to download the certificate. * Open the Settings app -> Security -> Encryption & Credentials -> Install a certificate -> CA certificate -> Install anyway, and select the Proxyman CA certificate in your storage. You can verify it in Trusted credentials -> User tab. ### 3. My Android physical device or emulator connection is not stable It's probably caused by the Android device or emulator. A possible fix is to change the DNS on your Mac or Android device to **8.8.8.8**. * **On macOS**: Open System Settings -> Network -> Wi-Fi -> Details… -> DNS, then add **8.8.8.8** to the DNS Servers list. * **On an Android device**: Open the Wi-Fi settings and set the DNS to **8.8.8.8**. Read more in [GitHub issue #636](https://github.com/ProxymanApp/Proxyman/issues/636). ### 4. The `adb` command is not found when using the Android Emulator automatic script If you try to override the Android Emulator and get the following error: ``` adb command line could not be found!!! ``` Install the `adb` command line tool, then try again. * [How to install ADB](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator#3-how-to-use-it) ### 5. Not sure how to install and trust the Proxyman certificate on an Android Emulator? Use the [Automatic Script for Android Emulator](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) --- Source: https://proxyman.com/docs/troubleshooting/ios-16-devices-issues # iOS 16 and iOS 17 issues > iPhone ignores the Wi-Fi proxy and Proxyman captures no traffic on iOS 16, 17, 18 or 26? Learn how to test for this iOS bug and fix it with Forget This Network. ## 1. Problem * iOS 16 or iOS 17 physical devices can't set the HTTP proxy to Proxyman in Settings app -> Wi-Fi -> Your Wi-Fi -> Configure Proxy -> Manual. * Proxyman might not capture the traffic from iOS 16/17 devices. \=> It's an Apple bug. > **Warning:** This issue happens with **Charles Proxy**, Wireshark, Fiddler Everywhere, and other web debugging proxy apps too. > **Tip:** Some users report that it's fixed on iOS 16.3 and later ✅ > > iOS 17 might have the same problem. **Forget This Network** might fix it. > > The same test and fix apply to iOS 18 and iOS 26. The Wi-Fi proxy settings are in the same place, so follow the same steps. > > See [Section 4](https://proxyman.com/docs/troubleshooting/ios-16-devices-issues#4-solution-for-ios-163-ios-17-or-later) for details. ## 2. How do I know it's a bug from Apple, not Proxyman? You can test it with these steps: 1. Quit the Proxyman app. 2. On your iPhone (iOS 16 or later), open the Settings app -> Wi-Fi -> Your Wi-Fi -> Configure Proxy -> Manual. 3. Set any random IP, for example 192.168.3.111. 4. Set any random port, for example 9999. 5. Save. 6. Open the Safari app and visit https://google.com. 7. Check whether you can access the internet. The IP and port are **invalid**, so the page should not load. If you can still access the internet, the iPhone is ignoring the proxy, which means it's Apple's bug 🆘 ## 3. Solution for iOS 16.3 or earlier * Forget the Wi-Fi network and restart the device. It might help. * Use the [Atlantis framework](https://github.com/ProxymanApp/atlantis) to inspect the network. * Try an iOS 15 physical device. * Try the iOS 16 **Simulator**. ## 4. Solution for iOS 16.3, iOS 17 or later These steps also work on iOS 18 and iOS 26. 1. Settings app -> Wi-Fi -> Your Wi-Fi -> **Forget This Network.** 2. Connect to the Wi-Fi again. Then open Settings app -> Wi-Fi -> Your Wi-Fi -> Configure Proxy -> Manual -> enter the IP and port -> Save. 3. Double-check the Configure Proxy setting. ![iOS Wi-Fi details with Configure Proxy set to Manual under HTTP Proxy](https://proxyman.com/docs/assets/IMG_7734727B4024-1.jpeg) _Configure Proxy must show Manual_ 4. Make sure it shows `Manual`. If it shows `Off`, set it again and save. Sometimes, the proxy setting is not saved. ## 5. Further discussions * [GitHub issue #1293](https://github.com/ProxymanApp/Proxyman/issues/1293) --- Source: https://proxyman.com/docs/troubleshooting/get-ssl-error-from-https-request-and-response # SSL Error from HTTPS Request/Response > Fix "SSL Handshake Failed" and other SSL errors in Proxyman. Check that the Proxyman certificate is installed and trusted, and rule out SSL pinning. ## 1. Problems * You can't see any HTTPS traffic in the Proxyman app. * You get SSL errors from HTTPS requests and responses. * You get **SSL Handshake Failed** or **Possible Certificate Pinning** in the Response panel. ![Proxyman Response panel showing Client SSL Handshake Failed with error code -9806](https://proxyman.com/docs/assets/Screen%20Shot%202020-04-25%20at%2019.52.38.png) ## 2. Solution There are many reasons for an SSL handshake failure. Walk through the steps below to find the problem. ## 2.1 Mobile devices ### iOS Device * Follow the [iOS Setup Guide](https://proxyman.com/docs/debug-devices/ios-device) -> Make sure you've installed and trusted the Proxyman CA certificate on your device. * If you're intercepting popular apps (for example Facebook, Instagram, Apple, WhatsApp, ...): They are protected by SSL pinning -> It's not possible to intercept them. * Verify that your iOS app doesn't use SSL pinning. If it does, disable it. ### iOS Simulator Follow the [iOS Simulator Setup Guide](https://proxyman.com/docs/debug-devices/ios-simulator) -> Make sure you've installed and trusted the Proxyman CA certificate on your simulator. ### Android Device * Follow the [Android Device Setup Guide](https://proxyman.com/docs/debug-devices/android-device) -> Make sure you've installed and trusted the Proxyman CA certificate on your device. * Verify that the 5th step is completed (add your domain to two files: **res/xml/network\_security\_config.xml** and **AndroidManifest.xml**). * If you're trying to intercept Android apps that you don't own -> It isn't possible to intercept them -> ❌ ### Android Emulator * Follow the [Android Emulator Setup Guide](https://proxyman.com/docs/debug-devices/android-device/automatic-script-for-android-emulator) -> Make sure you've installed and trusted the Proxyman CA certificate on your emulator. * Verify that the 5th step is completed (add your domain to two files: **res/xml/network\_security\_config.xml** and **AndroidManifest.xml**). * If you're trying to intercept Android apps that you don't own -> It isn't possible to intercept them -> ❌ ### React Native app * If your app is a React Native app, please follow the [React Native Guide](https://proxyman.com/docs/debug-devices/react-native). ### Flutter * Follow the [Flutter Setup Guide](https://proxyman.com/docs/debug-devices/flutter). Have you tried and verified all the steps above, but still get SSL errors? ### Verify that you're able to see HTTPS Request/Response from https://google.com without any errors 1. Get your device. 2. Open the web browser (Safari on iOS or Google Chrome on Android). 3. Visit **https://google.com** 4. In Proxyman for macOS, right-click the request and select **Enable SSL Proxying** for this domain. Then reload the page. 5. Check whether you can see the HTTPS response. #### ✅ Success 1. You can see the HTTPS response from https://google.com, which means you set up the certificate correctly ✅ 2. The problem might be in your app. Try again with your domains or apps -> If the SSL error still happens, the app is most likely protected by SSL pinning. 3. If you believe it's not an SSL pinning case, open a ticket on [GitHub](https://github.com/ProxymanApp/Proxyman/issues) (mention your device, OS version, app name, etc.). #### ❌ Failed! * The Proxyman certificate is probably not installed or trusted correctly on your device. Go back to the [2.1 Mobile devices](https://proxyman.com/docs/troubleshooting/get-ssl-error-from-https-request-and-response#21-mobile-devices) section and follow it. * If everything is done, but the SSL error still happens, open a ticket on [GitHub](https://github.com/ProxymanApp/Proxyman/issues) (mention your device, OS version, app name, etc.). ## 2.2 MacBook or Windows PC I get SSL errors from: * **Mac (MacBook, Mac mini, Mac Studio)** -> Install and trust the certificate on your Mac -> Follow the [macOS guide](https://proxyman.com/docs/debug-devices/macos) * **Windows** -> Install and trust the certificate on your Windows machine -> Follow the [Windows guide](https://proxyman.com/docs/proxyman-windows/install-certificate) * Java -> Follow the [Java VM guide](https://proxyman.com/docs/debug-devices/java) * Firefox -> Follow the [Firefox guide](https://proxyman.com/docs/debug-devices/firefox) * Python -> Follow the [Python guide](https://proxyman.com/docs/debug-devices/python) * Ruby -> Follow the [Ruby guide](https://proxyman.com/docs/debug-devices/ruby) > **Warning:** Some networking libraries (Ruby, NodeJS, Python, Golang) don't trust the self-signed certificate by default. You have to tell the library to trust the certificate. > > \=> To fix it, use [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup): open **Setup** -> **Automatic Setup…** -> **Open New Terminal…**, then run your script in that terminal. It sets up certificate trust for supported NodeJS, Python, Ruby and Golang libraries. For other libraries, search for **"\ self-signed certificate"**. ## 2.3 SSL-Pinning? * If you still can't see the HTTPS response from your app, your app is probably protected by [SSL pinning](https://en.wikipedia.org/wiki/HTTP_Public_Key_Pinning), which prevents MitM apps from seeing the content. Most popular apps (Facebook, Apple, Instagram, Messenger, etc.) use it. * Temporarily **disable SSL pinning** in your app and try again. Read more about SSL pinning: [Preventing Man-in-the-Middle Attacks in iOS with SSL Pinning](https://www.kodeco.com/1484288-preventing-man-in-the-middle-attacks-in-ios-with-ssl-pinning) > **Note:** Tried everything and still not sure what is wrong? Open a [GitHub ticket](https://github.com/ProxymanApp/Proxyman/issues). > > Please also mention: Proxyman macOS/Windows, your Proxyman version, your iOS/Android device, etc. ## Video [Video: Capture HTTP and HTTPS traffic with Proxyman](https://proxyman.com/videos/capture-http-https-traffic) (25 seconds) ## Learn more * [Can we bypass SSL pinning?](https://proxyman.com/posts/2019-11-15-Can-we-bypass-ssl-pinning) --- Source: https://proxyman.com/docs/troubleshooting/couldnt-see-any-request-from-localhost-server # I could not see any requests from my localhost server > localhost:3000 requests not showing in Proxyman? Capture localhost traffic from Google Chrome with Automatic Setup, or use /etc/hosts or localhost.proxyman.io. ## 1. Problem I develop a local NodeJS, Ruby, or Python backend at **http://localhost:3000**, but when I visit **http://localhost:3000** in Google Chrome or Safari, there is no traffic in the Proxyman app. **Why does this happen?** By default, on macOS, localhost requests don't go through the system HTTP proxy. Therefore, Proxyman doesn't record any traffic. ![Google Chrome open at localhost:4000 while the Proxyman request list stays empty](https://proxyman.com/docs/assets/capture_http_localhost_chrome_2.jpeg) _localhost traffic doesn't appear in Proxyman by default_ ## 2. Solution ### 2.1 ✅ New solution for v6.3.0 From Proxyman macOS v6.3.0, Proxyman can: * Capture `http://localhost:3000` or any localhost traffic in Google Chrome / Firefox without changing the /etc/hosts file * Works with a single click * Tutorial: [How to capture HTTP localhost traffic from Google Chrome](https://proxyman.com/posts/how-to-capture-http-localhost-traffic-from-google-chrome) #### How to do it 1. In Proxyman, open the **Setup** menu -> **Automatic Setup…** -> In the Web Browsers section, click **Google Chrome…** 2. A new Google Chrome window appears. 3. Done. Visit http://localhost:3000 and Proxyman captures it. ![Proxyman captures localhost:3000 and localhost:4000 requests from Google Chrome](https://proxyman.com/docs/assets/capture_http_localhost_chrome_1.jpeg) _Capture localhost traffic from Google Chrome_ ### 2.2 Old solution There are two solutions. Follow either one of them. #### Solution 1: Map **localhost** to a domain name in `/etc/hosts` 1. Open the `/etc/hosts` file with Vim or VS Code. ``` $ sudo vim /etc/hosts ``` 2\. Add a domain name for both **IPv4** and **IPv6** (you can replace `proxyman.debug` with any name) ``` 127.0.0.1 proxyman.debug ::1 proxyman.debug ``` ![The /etc/hosts file in VS Code with proxyman.debug mapped to 127.0.0.1 and ::1](https://proxyman.com/docs/assets/Screenshot%202023-09-01%20at%2022.11.30.png) _Add proxyman.debug in /etc/hosts_ 3\. Save the file with `sudo` permission. 4\. Access your localhost server at **http://proxyman.debug:3000** (replace 3000 with your localhost port). 5\. Enjoy debugging! > **Note:** If you use `local` as a suffix, for example proxyman.local, make sure to remove `*.local` from the Bypass Proxy List ([how to do it](https://proxyman.com/docs/troubleshooting/.local-doesnt-appear-in-proxyman#2-solution)). #### Solution 2: Use **localhost.proxyman.io** instead of **localhost** Proxyman uses Cloudflare and sets the DNS of **localhost.proxyman.io** to 127.0.0.1 (localhost). As a result, Proxyman can capture the local traffic as usual ✅ For example:
Old URLNew URL
Old URLNew URL
localhost:3000localhost.proxyman.io:3000
localhost:8080localhost.proxyman.io:8080
......
--- Source: https://proxyman.com/docs/troubleshooting/i-could-not-see-any-http-traffic-from-my-nodejs-python-or-ruby-scripts # I could not see any HTTP traffic from my NodeJS, Python, or Ruby scripts > NodeJS, Python, Ruby or Golang requests not showing in Proxyman? Capture them with Automatic Setup in one click, or with Network Extension on macOS 26. ## 1. Problem * I have NodeJS, Ruby, Python, or Golang scripts or servers that make HTTP/HTTPS requests. However, I don't see any traffic in the Proxyman app. For example: * NodeJS: I'm using the [axios](https://github.com/axios/axios) library to call a REST API on my production server (for example https://mycompany.com/v1/data). However, Proxyman doesn't record any traffic. * I'm using net/http in Golang, but no requests appear in Proxyman. * ... and so on. > **Note:** Try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension) to capture HTTP/HTTPS requests from scripts running on your Mac without setting a proxy in each library. For SSL errors, use [Automatic Setup](https://proxyman.com/docs/automatic-setup/automatic-setup) to set up certificate trust for supported libraries. > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## 2. New Automatic Solution (v4.7.0 or later) ✅ Proxyman v4.7.0 or later can capture HTTP/HTTPS traffic from Python, Ruby, NodeJS and Golang with one click. * One-click solution: no need to set the HTTP proxy or trust the self-signed certificate by hand. * Supports many network libraries for NodeJS, Python, Ruby, and Golang. ### 2.1 How to use 1. Open Proxyman -> **Setup** menu -> **Automatic Setup…** 2. Click **Open New Terminal…** ![Proxyman Automatic Setup window with Open New Terminal for NodeJS, Ruby, Python and Golang scripts](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Start a pre-configured Terminal_ 3. Accept the AppleScript permission prompt if needed. 4. A new Terminal window opens. Start your Python backend server or run your scripts there. Proxyman captures all their traffic. ![Proxyman capturing HTTPS requests from a Go script using net/http, fasthttp, resty and gorequest](https://proxyman.com/docs/assets/CleanShot%202025-03-18%20at%2009.56.44%402x.jpg) _Capture HTTPS traffic from Ruby, Python, NodeJS and Golang servers and scripts_ 5. Done ✅ ## 3. Other Problems ### 3.1 I can't see any `fetch()` request from a NextJS Server Component * See this blog post: [Capture HTTPS from NextJS Server Components](https://proxyman.com/posts/2024-06-10-Capture-HTTPS-From-NextJS-Server-Components) ## Learn more * [Capture HTTP/HTTPS requests from Axios in NodeJS](https://proxyman.com/posts/2023-05-14-Capture-HTTP-HTTPS-Request-From-Axios-NodeJS) * [Capture HTTP/HTTPS requests from Ruby net/http](https://proxyman.com/posts/2023-05-09-Capture-HTTP-HTTPS-Request-Response-From-Ruby-Net-HTTP-library) * [Capture HTTPS traffic from Python Requests and HTTPX](https://proxyman.com/posts/2025-01-29-How-To-Capture-HTTPS-Traffic-From-Python-Requests-httpx) --- Source: https://proxyman.com/docs/troubleshooting/.local-doesnt-appear-in-proxyman # \*.local requests do not appear on Proxyman > *.local requests not showing in Proxyman? Remove *.local from the macOS bypass proxy list, or try Network Extension for local network servers. ## 1. Problem * All requests appear in Proxyman, except some local requests (`*.local` or `localhost`). > **Note:** For `.local` servers on your local network, try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension) to capture HTTP/HTTPS traffic from Mac apps that bypass the system proxy. For `localhost` requests, use the setup guide below. > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## 2. Solution * If it's a `localhost` request, read the following page: - [I could not see any requests from my localhost server](https://proxyman.com/docs/troubleshooting/couldnt-see-any-request-from-localhost-server) * If it's a `*.local` request: Open **System Settings** -> **Network** -> **Wi-Fi** -> **Details…** -> **Proxies**, then remove `*.local` from "Bypass proxy settings for these hosts & domains". ![macOS Wi-Fi Proxies settings with *.local in the bypass proxy list](https://proxyman.com/docs/assets/Screen_Shot_2020-04-26_at_09_40_48.png) If you installed the Proxy Helper Tool, Proxyman uses its own [Bypass Proxy List](https://proxyman.com/docs/basic-features/bypass-proxy-list) while it runs. Open **Tools** -> **Proxy Settings** -> **Bypass Proxy Settings…** in Proxyman and make sure `*.local` is not in the list. ![Proxyman Bypass Proxy Settings window with a comma-separated domain list and no *.local entry](https://proxyman.com/docs/assets/proxyman-bypass-proxy-settings.jpg) _Bypass Proxy Settings in Proxyman_ --- Source: https://proxyman.com/docs/troubleshooting/i-couldnt-see-any-traffics-on-proxyman # I couldn't see any traffics on Proxyman > Proxyman not capturing any requests, or the request list is empty? Check the system proxy, recording, filters, VPN apps and cached responses. An empty request list usually means traffic is not reaching Proxyman, recording is paused, or a filter hides the requests. Check the proxy and capture settings first, then test for VPN conflicts and cached responses. ## 1. Problems * After launching the app, the request list is empty. * Proxyman doesn't capture any requests. * I don't see any requests in the app. * I can see some requests from my Mac, but no requests from my remote devices (iOS, Android). > **Note:** For remote devices (iOS or Android), see [My remote devices could not connect to Proxyman](https://proxyman.com/docs/troubleshooting/my-ios-devices-couldnt-connect-to-proxyman-via-proxy). ![Empty Proxyman request list with 0 apps and 0 domains captured](https://proxyman.com/docs/assets/Screen_Shot_2020-04-26_at_09_48_10.png) > **Note:** If an app on your Mac ignores the system proxy, try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension). Open Proxyman -> Settings -> Network Extension, enable it, then restart the app and make a new request. > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## 2. Solution Work through these checks in order, making a fresh request after each change: 1. **Check the proxy:** Confirm that your client uses the computer and port where Proxyman is listening. For local Mac traffic, check the HTTP and HTTPS system proxy values below. For an iOS or Android device, use the computer IP address from its Proxyman setup guide. 2. **Check capture settings:** Make sure recording is on (**Tools** -> **Toggle Recording**) and clear any active request filters. If HTTP appears but HTTPS cannot be read, verify certificate trust and [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying) for the domain. 3. **Check VPN interaction:** Temporarily disconnect the VPN if possible, then recheck proxy settings and repeat the request. Some VPN clients overwrite the proxy configuration. 4. **Check cached requests:** Repeat an action that sends a new network request, or try the No Caching tool described below. A response served entirely from the app cache will not pass through the proxy. The sections below explain the proxy, VPN, helper-tool, and caching checks in more detail. ### 2.1 Turn OFF all VPN apps on your Mac Some VPN apps revert the HTTP proxy in the network settings as soon as Proxyman overrides it. As a result, HTTP traffic doesn't go through the Proxyman port 9090. Close all VPN apps if possible and relaunch Proxyman. If you need your VPN, see [Proxyman does not work with VPN apps](https://proxyman.com/docs/troubleshooting/proxyman-does-not-work-with-vpn-apps). ### 2.2 Double-check the HTTP proxy in Network settings Proxyman overrides the HTTP proxy at launch and reverts it when it quits, but some apps can change it back. Open System Settings -> Network -> Wi-Fi -> Details… -> Proxies: * Check **Web proxy (HTTP)** and **Secure web proxy (HTTPS)** * Make sure the port is the same as the Proxyman port * The server is **127.0.0.1** Click OK and check the requests in Proxyman. ![macOS Wi-Fi Proxies settings with Web Proxy and Secure Web Proxy set to 127.0.0.1 port 9090](https://proxyman.com/docs/assets/Screen%20Shot%202020-04-26%20at%2009.54.53.png) ### 2.3 Install the Proxy Helper Tool By default, Proxyman overrides the system HTTP proxy with the `networksetup` command line tool, but it can fail in some cases. \=> Install the Proxy Helper Tool. It overrides the system HTTP proxy properly. Open Proxyman **Settings** -> **Advanced** -> **Proxy Helper Tool** -> **Install**. ![Proxyman Advanced settings with the Proxy Helper Tool installed (version 1.7.0) and an Uninstall button](https://proxyman.com/docs/assets/proxyman-settings-advanced-proxy-helper-tool.jpg) _Proxy Helper Tool installed_ ### 2.4 Some HTTP/HTTPS requests are missing from Proxyman Alamofire or URLSession might use a cached response for your request. As a result, the request never reaches the server, so Proxyman can't capture and show it. Solution: * Turn off caching in URLSession or Alamofire. * Use the [No Caching tool](https://proxyman.com/docs/advanced-features/no-caching) (⌥⌘N). ## Video [Video: Capture HTTP and HTTPS traffic with Proxyman](https://proxyman.com/videos/capture-http-https-traffic) (25 seconds) --- Source: https://proxyman.com/docs/troubleshooting/couldnt-see-any-requests-from-3rd-party-network-libraries # I couldn't see any requests from 3rd-party network libraries > Requests from axios, fetch, Alamofire, Ktor or cURL not showing in Proxyman? Use Automatic Setup, Network Extension, or set the HTTP proxy in the library. ## 1. Problem * I can see other requests in Proxyman, but not the ones from my website, NodeJS, iOS, or Android app that use 3rd-party network libraries, such as [fetch](https://github.com/github/fetch), [axios](https://github.com/axios/axios), [Alamofire](https://github.com/Alamofire/Alamofire), [Ktor Apache HttpClient](https://ktor.io), curl, ... > **Note:** If a library running on your Mac ignores proxy settings, try [Network Extension](https://proxyman.com/docs/advanced-features/network-extension). It captures supported HTTP/HTTPS traffic without changing the library's proxy settings. HTTPS still needs certificate trust and [SSL Proxying](https://proxyman.com/docs/basic-features/ssl-proxying). > > Network Extension is BETA and requires Proxyman PRO on macOS 26 or later. ## 2. New Automatic Solution (v4.7.0 or later) ✅ Proxyman v4.7.0 or later can capture HTTP/HTTPS traffic from NodeJS, Python and Ruby scripts with one click. * One-click solution: no need to set the HTTP proxy or trust the self-signed certificate by hand. * Supports NodeJS, Ruby and Python. Newer versions also support Golang. ### How to use 1. Open Proxyman -> **Setup** menu -> **Automatic Setup…** 2. Click **Open New Terminal…** 3. Accept the AppleScript permission prompt if needed. 4. A new Terminal window opens. Start your Python backend server or run your scripts there. Proxyman captures all their traffic. 5. Done ✅ ![Proxyman Automatic Setup window with Terminal App, Web Browsers and ElectronJS App sections](https://proxyman.com/docs/assets/proxyman-automatic-setup-window.jpg) _Open a pre-configured Terminal with Automatic Setup_ See [I could not see any HTTP traffic from my NodeJS, Python, or Ruby scripts](https://proxyman.com/docs/troubleshooting/i-could-not-see-any-http-traffic-from-my-nodejs-python-or-ruby-scripts) for more details. ## 3. Old Solution (Not recommended ❌) In general, you have to set up the network library to use an HTTP proxy that points to the Proxyman port (9090 by default). List of possible solutions: * Fetch: [Using a proxy like Fiddler with the Fetch API (Stack Overflow)](https://stackoverflow.com/questions/44524236/using-proxy-like-fiddler-with-fetch-api) * cURL: Use the _--proxy_ flag. For example: ``` $ curl -v "https://httpbin.org/get?id=123" --proxy localhost:9090 ``` Read more: [cURL with a proxy (Stack Overflow)](https://stackoverflow.com/a/9445516/3127477) * Ktor: [Ktor client proxy documentation](https://ktor.io/docs/client-proxy.html) * Alamofire: [Alamofire with a proxy (Stack Overflow)](https://stackoverflow.com/a/42754358/3127477) ### Axios You can set the HTTP proxy in Axios. Then all its traffic appears in Proxyman. ```javascript axios.get({ url: '/v1/user/data', // 'proxy' defines the hostname and port of the proxy server // Use `false` to disable proxies, ignoring environment variables. // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and // supplies credentials. // This will set an `Proxy-Authorization` header, overwriting any existing // `Proxy-Authorization` custom headers you have set using `headers`. proxy: { host: '127.0.0.1', port: 9090 } }); ``` Proxyman listens on port 9090 by default. To find your Mac's IP address and port, see the [iOS setup guide](https://proxyman.com/docs/debug-devices/ios-device#ios-setup-guide). ## Learn more * [Capture HTTP/HTTPS requests from Axios in NodeJS](https://proxyman.com/posts/2023-05-14-Capture-HTTP-HTTPS-Request-From-Axios-NodeJS) --- Source: https://proxyman.com/docs/troubleshooting/breakpoint-modify-request-response-by-raw-message # \[Breakpoint] Modify Request/Response by Raw Message > Fix "Invalid Request HTTP Message" or "Invalid Response HTTP Message" when you edit a raw request or response in the Proxyman Breakpoint Raw tab. When you edit a request or response in the **Raw** tab of a [Breakpoint](https://proxyman.com/docs/advanced-features/breakpoint), Proxyman checks the HTTP message as you type. If the syntax is wrong, it shows an error at the bottom of the editor, such as **Invalid Header**, **Invalid Request HTTP Message** or **Invalid Response HTTP Message**. Your change is not applied until the message is valid again. ![Proxyman Breakpoint Raw tab showing an Invalid Header error for the line X-Debug true, which has no colon](https://proxyman.com/docs/assets/proxyman-breakpoint-raw-invalid-header.jpg) _A header line without a colon is invalid_ ## How to fix it * The first line of a request is the method, the path and the HTTP version, for example `GET /get?id=123 HTTP/1.1`. * The first line of a response is the HTTP version and the status, for example `HTTP/1.1 200 OK`. * Put each header on its own line, as `Name: Value`. * Leave one empty line between the headers and the body. * To turn off a header without deleting it, start its line with `//`. * To start over, use **Reset to the Original** to restore the original message. ## Video [Video: Modify requests and responses with Breakpoint](https://proxyman.com/videos/breakpoint-tool) (30 seconds) --- Source: https://proxyman.com/docs/troubleshooting/could-not-change-proxyman-app-icons # Could not change Proxyman App Icons > Proxyman Dock icon not changing after you pick a new one? Restart the Dock Extra process in Activity Monitor, then select the app icon again. ## 1. Problems? Proxyman 3.2.0 introduced new app icons that help you tell Proxyman apart from other apps in the Dock. You might see the following issue: * The icon doesn't change when you pick a new one in **Settings** -> **Appearance** -> **Proxyman Dock Icon**. ![Proxyman Appearance settings with the Dock Icon options On Earth, On Mars, Space Candy and Classic](https://proxyman.com/docs/assets/proxyman-settings-appearance-dock-icon.jpg) _Dock icon options in Appearance settings_ ## 2. Solution 1. Quit Proxyman, then open Activity Monitor. 2. Search for "Dock" in the search bar. 3. Select **Dock Extra** and quit it with the stop (X) button in the toolbar. 4. Relaunch Proxyman and select your favorite app icon. ![Activity Monitor search for Dock with the Dock Extra processes selected](https://proxyman.com/docs/assets/Screen_Shot_2022-03-05_at_15_07_41.png) --- Source: https://proxyman.com/docs/troubleshooting/lost-data-after-updating-proxyman-app # Lost data after updating Proxyman app? > Lost your Proxyman rules or settings after an update? Restore Map Local, Scripting, Breakpoint and other data from Proxyman's automatic backup folder. ## Problem After updating the app to the latest version, you might see that: * Your data, including all debugging tool rules (Map Local, Scripting, Breakpoint, SSL Proxying List, ...) and user settings, is wiped out. > **Note:** Proxyman makes sure your data **is never lost**. Still, it's good to have a backup of your valuable data ⚡️. ## How to recover 1. Open the backup folder at `~/Library/Application Support/com.proxyman.NSProxy/user-data-backups` 2. Unzip the latest backup file. (In Finder, sort by "Date Added" to find the latest backup.) 3. Copy each folder from the backup to the app folder at `~/Library/Application Support/com.proxyman.NSProxy` For instance:
Copy FromCopy To
~/Library/Application Support/com.proxyman.NSProxy/user-data-backups/userdata_proxyman_3.6.0_05-24-2022-11-55-20/user-data~/Library/Application Support/com.proxyman.NSProxy/user-data
~/Library/Application Support/com.proxyman.NSProxy/user-data-backups/userdata_proxyman_3.6.0_05-24-2022-11-55-20/map-local~/Library/Application Support/com.proxyman.NSProxy/map-local
and more...
A backup contains the `user-data`, `map-local`, `scripts` and `users` folders. > **Note:** If you use Proxyman from Setapp, the app folder is `~/Library/Application Support/com.proxyman.NSProxy-setapp`. ## When does Proxyman back up my data? After you update Proxyman to a newer version, Proxyman backs up your current data and saves it to `~/Library/Application Support/com.proxyman.NSProxy/user-data-backups`. To make your own backup at any time, use **Tools** -> **Import / Export Settings** -> **Export (Backup)…**. See [Import / Export Settings](https://proxyman.com/docs/basic-features/import-export-settings). --- Source: https://proxyman.com/docs/troubleshooting/proxyman-consumes-too-much-ram-and-unresponsive # Proxyman consumes too much RAM & unresponsive > Proxyman using too much memory, slow or not responding? Remove * wildcard and web browser rules from the SSL Proxying List and keep auto cleanup on. ## Problems Proxyman might: * Become unresponsive after you use it for a while. * Use too much memory. You might see these problems if you enable SSL Proxying with the following rules: * The `*` wildcard, which intercepts all traffic from your Mac. * Whole web browsers (Google Chrome, Safari, Firefox, etc.). ## **Reason** Proxyman intercepts and decrypts all of that traffic, which leads to high memory usage. In the worst case, the app can become unresponsive. ![Proxyman SSL Proxying List with Safari, Google Chrome and Firefox enabled and a warning that this can slow your Mac](https://proxyman.com/docs/assets/Screen_Shot_2022-08-10_at_14_01_16.png) ## Solution 1. ✅ Update to the latest Proxyman version. (Memory leaks are fixed in the latest builds.) 2. Open **Tools** -> **SSL Proxying List…** 3. Remove all web browsers and `*` wildcards if they exist. 4. Enable SSL Proxying only on the domains you need. 5. Keep **Automatically Remove Older Requests** on in **Settings** -> **Advanced**. It removes older requests when memory goes over the limit. Click **Edit…** to change the limit. ![Proxyman Advanced settings with Automatically Remove Older Requests turned on and an Edit button](https://proxyman.com/docs/assets/proxyman-settings-advanced-proxy-helper-tool.jpg) _Automatically Remove Older Requests_