# 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](https://proxyman.com/docs/es/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. > **Nota:** 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 {#1-set-up} Añade Proxyman MCP a tu agente con `--headless` al final del comando. ### Claude Code {#claude-code} ```bash claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless ``` ### Codex {#codex} ```bash codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless ``` ### Cursor y otros clientes MCP {#cursor-and-other-mcp-clients} ```json { "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 {#2-capture-https-with-no-dialogs} 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](https://proxyman.com/docs/es/basic-features/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 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= node app.js` | | Python (requests, httpx) | `HTTPS_PROXY=http://127.0.0.1:9090 SSL_CERT_FILE= REQUESTS_CA_BUNDLE= 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= --user-data-dir=`. Chrome ignora la lista SPKI sin `--user-data-dir`. | | Firefox | `run_guided_setup` con `firefox` (cierra Firefox antes). Consulta [Firefox](https://proxyman.com/docs/es/debug-devices/firefox). | | iOS Simulator | `install_ios_simulator_certificate`. Consulta [iOS Simulator](https://proxyman.com/docs/es/debug-devices/ios-simulator). | Los mismos pasos a mano, con 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. Qué cambia en el modo headless {#3-what-changes-in-headless-mode} * **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](https://proxyman.com/docs/es/advanced-features/network-extension). * **Sin alertas ni ventanas.** Lo que sería una alerta se imprime en stdout. Un [Breakpoint](https://proxyman.com/docs/es/advanced-features/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](https://proxyman.com/docs/es/advanced-features/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 {#4-what-still-needs-you-once} 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](https://proxyman.com/docs/es/debug-devices/ios-device). ## 5. Ejecútalo desde una shell o CI {#5-run-it-from-a-shell-or-ci} También puedes iniciar Proxyman en modo headless sin un agente: ```bash /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 `. Usa [proxyman-cli](https://proxyman.com/docs/es/command-line) para trabajar con él, por ejemplo para exportar el tráfico capturado: ```bash 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 {#learn-more} * [MCP](https://proxyman.com/docs/es/mcp) * [Línea de comandos](https://proxyman.com/docs/es/command-line) * [Proxyman ahora funciona en modo headless para agentes de IA](https://proxyman.com/posts/2026-11-13-proxyman-headless-mode-for-ai-agents)