Modo headless

Ejecuta Proxyman sin ventana, sin icono en el Dock y sin diálogos, para que agentes de IA y scripts capturen y descifren HTTPS mediante MCP. Disponible en Proxyman 26.6.0 o posterior.

El modo headless ejecuta Proxyman sin interfaz: sin ventana, sin icono en el Dock ni en la barra de menús y sin diálogos. Tu agente de IA, como Claude Code, Codex o Cursor, inicia Proxyman mediante MCP, captura y descifra HTTPS, lee el tráfico y crea reglas de depuración, todo por sí mismo. Funciona como mitmproxy, con todas las herramientas de Proxyman.

información

El modo headless está disponible en Proxyman 26.6.0 o posterior. Como el resto de Proxyman MCP, requiere una licencia de pago de Proxyman.

Claude Code inicia Proxyman en modo headless, crea el certificado sin ningún diálogo, envía HTTPS a través de 127.0.0.1:9090 y lee el flujo descifrado. No se abre ninguna ventana de Proxyman.

1. Configuración

Añade Proxyman MCP a tu agente con --headless al final del comando.

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 y otros clientes MCP

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

Para la versión de Setapp, usa /Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server.

Eso es todo. No necesitas abrir Proxyman ni activar Settings → MCP: la primera llamada a una herramienta inicia Proxyman en modo headless, y se cierra cuando tu agente termina.

consejo

¿Ya añadiste Proxyman MCP sin --headless? Pide a tu agente que "inicie Proxyman en modo headless". Llamará a open_proxyman con headless: true.

2. Captura HTTPS sin diálogos

Pide a tu agente, por ejemplo:

Inicia Proxyman en modo headless, crea su CA sin ningún diálogo y descifra api.example.com. Después ejecuta mis pruebas a través de 127.0.0.1:9090 y muéstrame las solicitudes fallidas.

Esto es lo que hace, paso a paso:

1. Iniciar Proxyman: open_proxyman con headless: true. Devuelve la dirección del proxy, http://127.0.0.1:9090 de forma predeterminada.
2. Crear el certificado: install_certificate con mode: generate_only crea la CA de Proxyman y la añade al llavero de inicio de sesión sin marcarla como de confianza, así que macOS no muestra ningún diálogo. Devuelve certificate_path (un archivo PEM) y spki_sha256.
3. Descifrar un dominio: enable_ssl_proxying para api.example.com, o un comodín como *.example.com. Consulta SSL Proxying.
4. Enviar tráfico: cada cliente usa el proxy y confía en la CA por sí mismo (consulta la tabla de abajo).
5. Leer el tráfico: get_flows, filter_flows y get_flow_detail devuelven las solicitudes y respuestas descifradas.

Cliente	Proxy y certificado
curl	curl -x http://127.0.0.1:9090 --cacert <certificate_path> https://api.example.com
Node.js 22.21+ o 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
Cualquier herramienta de shell	Ejecuta el comando de get_terminal_manual_command en la misma shell. Configura el proxy y el certificado para Node.js, Python, Ruby y curl, también para versiones anteriores de 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 ignora la lista SPKI sin --user-data-dir.
Firefox	run_guided_setup con firefox (cierra Firefox antes). Consulta Firefox.
iOS Simulator	install_ios_simulator_certificate. Consulta iOS Simulator.

Los mismos pasos a mano, con 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. Qué cambia en el modo headless

• La grabación siempre está activada. Proxyman no cambia el proxy del sistema de macOS, así que solo se capturan los clientes que apuntas a 127.0.0.1:9090. Para capturar todas las apps, pide a tu agente que llame a set_system_proxy o usa la Network Extension.
• Sin alertas ni ventanas. Lo que sería una alerta se imprime en stdout. Un Breakpoint no abre una ventana: tu agente lo resuelve con list_pending_breakpoints y resolve_breakpoint.
• Todas las herramientas de MCP funcionan, salvo las pocas que solo cambian lo que muestra una ventana, como open_proxyman_screen y set_flow_filter. Filtra con get_flows o filter_flows.
• Archivos de sesión: open_session_file abre un archivo de sesión, HAR o de registro como la sesión que lee tu agente, y close_session_file vuelve al tráfico en vivo.
• Access Control nunca pregunta. Cualquier dispositivo que llegue al puerto del proxy puede usarlo. Para aceptar solo este Mac, pide a tu agente que active proxy.listen_on_localhost_only con update_settings. Consulta Access Control.
• Muestra la ventana cuando quieras: abre Proxyman.app, o llama a open_proxyman con headless: false. El tráfico capturado se conserva.
• Un solo Proxyman a la vez: si Proxyman ya está abierto con una ventana, MCP usa esa instancia y no se inicia una segunda en modo headless.

4. Lo que aún necesita tu intervención una vez

El modo headless nunca muestra un diálogo, así que estos pasos los haces tú, una sola vez:

• Safari, apps que usan el almacén de confianza de macOS (URLSession) y Go: solo aceptan un certificado de confianza. Ejecuta install_certificate con mode: automatic una vez; macOS te pedirá la contraseña. Crea una CA nueva, así que configura después la confianza por cliente indicada arriba.
• set_system_proxy: el Helper Tool te pide la contraseña la primera vez.
• Network Extension: macOS te pide permitirla una vez.
• Un iPhone o dispositivo Android físico: instala el certificado en el dispositivo y confía en él. Consulta Depurar en dispositivos.

5. Ejecútalo desde una shell o CI

También puedes iniciar Proxyman en modo headless sin un agente:

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

Imprime líneas de estado en stdout y se ejecuta hasta que pulses Ctrl+C o ejecutes kill <pid>. Usa proxyman-cli para trabajar con él, por ejemplo para exportar el tráfico capturado:

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

aviso

No lo inicies con open -a Proxyman --args --headless. Si Proxyman ya está en ejecución, macOS descarta el argumento y muestra la ventana.

Más información

• MCP
• Línea de comandos
• Proxyman ahora funciona en modo headless para agentes de IA