Skip to main content

Headless Mode

Run Proxyman with no window, Dock icon or dialogs, so AI agents and scripts capture and decrypt HTTPS over MCP. Available in Proxyman 26.6.0 or later.

Headless mode runs Proxyman with no window, no Dock or menu bar icon, and no dialogs. Your AI agent, such as Claude Code, Codex or Cursor, starts Proxyman over MCP, captures and decrypts HTTPS, reads the traffic and creates debugging rules, all by itself. It works like mitmproxy, with every Proxyman tool.

info

Headless mode is available in Proxyman 26.6.0 or later. Like the rest of Proxyman MCP, it needs a paid Proxyman license.

Claude Code starts Proxyman headless, creates the certificate with no dialog, sends HTTPS through 127.0.0.1:9090 and reads the decrypted flow. No Proxyman window opens.

1. Set up​

Add Proxyman MCP to your agent with --headless at the end of the command.

Claude Code​

claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Codex​

codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Cursor and other MCP clients​

{
  "mcpServers": {
    "proxyman": {
      "command": "/Applications/Proxyman.app/Contents/MacOS/mcp-server",
      "args": ["--headless"]
    }
  }
}

For the Setapp version, use /Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server.

That's all. You don't need to open Proxyman or turn on Settings → MCP: the first tool call starts Proxyman headless, and it quits when your agent is done.

tip

Already added Proxyman MCP without --headless? Ask your agent to "start Proxyman in headless mode". It calls open_proxyman with headless: true.

2. Capture HTTPS with no dialogs​

Ask your agent, for example:

Start Proxyman headless, create its CA with no dialog, and decrypt api.example.com. Then run my tests through 127.0.0.1:9090 and show me the failed requests.

Here is what it does, step by step:

  1. Start Proxyman: open_proxyman with headless: true. It returns the proxy address, http://127.0.0.1:9090 by default.
  2. Create the certificate: install_certificate with mode: generate_only creates the Proxyman CA and adds it to the login Keychain without trusting it, so macOS shows no dialog. It returns certificate_path (a PEM file) and spki_sha256.
  3. Decrypt a domain: enable_ssl_proxying for api.example.com, or a wildcard such as *.example.com. See SSL Proxying.
  4. Send traffic: each client uses the proxy and trusts the CA itself (see the table below).
  5. Read the traffic: get_flows, filter_flows and get_flow_detail return the decrypted requests and responses.
ClientProxy and certificate
curlcurl -x http://127.0.0.1:9090 --cacert <certificate_path> https://api.example.com
Node.js 22.21+ or 24.5+HTTPS_PROXY=http://127.0.0.1:9090 NODE_USE_ENV_PROXY=1 NODE_EXTRA_CA_CERTS=<certificate_path> node app.js
Python (requests, httpx)HTTPS_PROXY=http://127.0.0.1:9090 SSL_CERT_FILE=<certificate_path> REQUESTS_CA_BUNDLE=<certificate_path> python app.py
Any shell toolRun the command from get_terminal_manual_command in the same shell. It sets the proxy and the certificate for Node.js, Python, Ruby and curl, also for older Node.js.
Chrome, Playwright, Puppeteer--proxy-server=http://127.0.0.1:9090 --ignore-certificate-errors-spki-list=<spki_sha256> --user-data-dir=<temp folder>. Chrome ignores the SPKI list without --user-data-dir.
Firefoxrun_guided_setup with firefox (quit Firefox first). See Firefox.
iOS Simulatorinstall_ios_simulator_certificate. See iOS Simulator.

The same steps by hand, with curl:

# 1. certificate_path from install_certificate or get_certificate_status
CA="$HOME/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem"

# 2. Send an HTTPS request through Proxyman
curl -x http://127.0.0.1:9090 --cacert "$CA" https://httpbin.org/json

3. What changes in headless mode​

  • Recording is always on. Proxyman doesn't change the macOS system proxy, so only the clients you point at 127.0.0.1:9090 are captured. To capture every app, ask your agent to call set_system_proxy or use the Network Extension.
  • No alerts or windows. What would be an alert is printed on stdout instead. A Breakpoint doesn't open a window: your agent resolves it with list_pending_breakpoints and resolve_breakpoint.
  • Every MCP tool works, except the few that only change what a window shows, such as open_proxyman_screen and set_flow_filter. Filter with get_flows or filter_flows instead.
  • Session files: open_session_file opens a session, HAR or log file as the session your agent reads, and close_session_file goes back to the live traffic.
  • Access Control never asks. Any device that reaches the proxy port can use it. To accept only this Mac, ask your agent to turn on proxy.listen_on_localhost_only with update_settings. See Access Control.
  • Show the window any time: open Proxyman.app, or call open_proxyman with headless: false. The captured traffic stays.
  • One Proxyman at a time: if Proxyman is already open with a window, MCP uses it, and a second, headless one doesn't start.

4. What still needs you once​

Headless mode never shows a dialog, so these steps need you, one time:

  • Safari, apps that use the macOS trust store (URLSession) and Go: they only accept a trusted certificate. Run install_certificate with mode: automatic once; macOS asks for your password. It creates a new CA, so set up the per-client trust above after it.
  • set_system_proxy: the Helper Tool asks for your password the first time.
  • Network Extension: macOS asks you to allow it once.
  • A physical iPhone or Android device: install and trust the certificate on the device. See Debug on Devices.

5. Run it from a shell or CI​

You can also start headless Proxyman without an agent:

/Applications/Proxyman.app/Contents/MacOS/Proxyman --headless &

It prints status lines on stdout and runs until you press Ctrl+C or run kill <pid>. Use proxyman-cli to work with it, for example to export the captured traffic:

proxyman-cli export-log -m all -f har -o session.har
warning

Don't start it with open -a Proxyman --args --headless. If Proxyman is already running, macOS drops the argument and shows the window instead.

Learn more​

Last updated on