# 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](https://proxyman.com/docs/mcp), captures and decrypts HTTPS, reads the traffic and creates debugging rules, all by itself. It works like mitmproxy, with every Proxyman tool.

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

<figure class="gb-embed gb-embed--video"><video controls playsinline muted preload="metadata" width="2560" height="1600" src="https://proxyman.com/assets/video/proxyman-mcp-headless-demo.mp4" poster="https://proxyman.com/assets/images/home-2026/proxyman-mcp-headless-demo-poster.webp" aria-label="Claude Code starts Proxyman in headless mode, creates its certificate with no dialog, and reads a decrypted HTTPS request over MCP"></video><figcaption><p>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.</p></figcaption></figure>

## 1. Set up

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

### Claude Code

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

### Codex

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

### Cursor and other MCP clients

```json
{
  "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](https://proxyman.com/docs/basic-features/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.

| Client | Proxy and certificate |
| --- | --- |
| curl | `curl -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 tool | Run 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`. |
| Firefox | `run_guided_setup` with `firefox` (quit Firefox first). See [Firefox](https://proxyman.com/docs/debug-devices/firefox). |
| iOS Simulator | `install_ios_simulator_certificate`. See [iOS Simulator](https://proxyman.com/docs/debug-devices/ios-simulator). |

The same steps by hand, with curl:

```bash
# 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](https://proxyman.com/docs/advanced-features/network-extension).
* **No alerts or windows.** What would be an alert is printed on stdout instead. A [Breakpoint](https://proxyman.com/docs/advanced-features/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](https://proxyman.com/docs/advanced-features/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](https://proxyman.com/docs/debug-devices/ios-device).

## 5. Run it from a shell or CI

You can also start headless Proxyman without an agent:

```bash
/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](https://proxyman.com/docs/command-line) to work with it, for example to export the captured traffic:

```bash
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

* [MCP](https://proxyman.com/docs/mcp)
* [Command-line](https://proxyman.com/docs/command-line)
* [Proxyman now runs headless for AI agents](https://proxyman.com/posts/2026-11-13-proxyman-headless-mode-for-ai-agents)