HeadlessX se presenta como un servidor de automatización de navegador sin interfaz (browserless), libre y de código abierto (licencia MIT), que apuesta por algo poco habitual en proyectos similares: comportamiento humano creíble (movimientos de ratón, scroll y aleatoriedad conductual), 40+ técnicas antidetención, despliegue en Docker o Node.js + PM2, y una arquitectura modular pensada para escalar, auditar y mantener en entornos reales. La propuesta nace como alternativa ligera a soluciones consolidadas como Browserless y está construida sobre Node.js y Playwright.
El repositorio oficial detalla una unificación de sitio web y API bajo el mismo dominio, lo que simplifica la publicación y el acceso a documentación, endpoints y estado del servicio. La idea es que cualquier equipo —desde una startup hasta un departamento de datos de una gran empresa— pueda levantar un “scraping server” fiable con autenticación por token, límites de tasa a nivel Nginx, logs estructurados y endpoints listos para extraer HTML, texto limpio, capturas y PDF, además de un modo batch para varias URL en paralelo.
El proyecto incorpora más de cuarenta técnicas antidetención combinadas con interacciones humanas sintéticas (ratón, scroll, tiempos de espera y aleatoriedad controlada). Este enfoque eleva la tasa de éxito frente a mecanismos anti-bot y reduce la necesidad de reprogramar scripts cuando cambian las defensas del sitio objetivo.
HeadlessX prioriza el despliegue rápido:
setup.sh).La configuración se centraliza en .env (dominio, subdominio, AUTH_TOKEN, límites de navegador, puerto, etc.). El resultado: un único dominio que sirve web + API y se administra con PM2 o docker-compose.
La versión v1.2.0 reescribe el servidor monolítico en 20+ módulos separados (config, servicios, controladores, middleware, utils). ¿Qué aporta?
Para equipos de datos y compliance, esto significa operar scraping con disciplina de software: quién hizo la petición, qué respondió, cuánto tardó y cómo se comportó el navegador.
HeadlessX expone endpoints coherentes y minimalistas:
GET /api/health → Health check (sin auth).GET /api/status?token=... → Estado del servidor (con auth).POST /api/render → Renderizado completo (JSON).GET/POST /api/html → HTML crudo.GET/POST /api/content → Texto limpio (contenido “readable”).GET /api/screenshot → Screenshot (con opciones como fullPage=true).GET /api/pdf → PDF de la página.POST /api/batch → Procesamiento por lotes de varias URL.Autenticación flexible (parámetro token, cabecera X-Token o Authorization: Bearer), timeouts configurables, y opciones como waitForSelector o humanBehavior. En la práctica, se integra en minutos con n8n (nodo de comunidad), Make, Zapier, Python y JavaScript.
Ejemplos rápidos:
HTML (cURL):
curl -X POST "https://subdominio.dominio.com/api/html?token=TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "timeout": 30000}'
Lenguaje del código: JavaScript (javascript)Screenshot:
curl "https://subdominio.dominio.com/api/screenshot?token=TU_TOKEN&url=https://example.com&fullPage=true" \
-o captura.png
Lenguaje del código: JavaScript (javascript)PDF:
curl -X POST "https://subdominio.dominio.com/api/pdf?token=TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "format": "A4"}' -o pagina.pdf
Lenguaje del código: JavaScript (javascript)Batch:
curl -X POST "https://subdominio.dominio.com/api/batch?token=TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"urls":["https://example1.com","https://example2.com"],"timeout":30000,"humanBehavior":true}'
Lenguaje del código: JavaScript (javascript)Opción recomendada (Docker):
git clone https://github.com/SaifyXPRO/HeadlessX.git
cd HeadlessX
cp .env.example .env
nano .env # DOMAIN, SUBDOMAIN, AUTH_TOKEN
docker-compose up -d
Lenguaje del código: PHP (php)SSL con Certbot (standalone o detrás de Nginx), gestión con docker-compose ps/logs/restart/down.
Opción Node.js + PM2 (instalación automática):
git clone https://github.com/SaifyXPRO/HeadlessX.git
cd HeadlessX
cp .env.example .env && nano .env
chmod +x scripts/setup.sh
sudo ./scripts/setup.sh
Lenguaje del código: PHP (php)El script compila el sitio, prepara Nginx, levanta PM2 y deja el servicio en marcha con logs consultables (npm run pm2:logs).
Desarrollo local:
cp .env.example .env
# DOMAIN=localhost, SUBDOMAIN=headlessx, AUTH_TOKEN=development_token_123
npm install
cd website && npm install && npm run build && cd ..
npm start # http://localhost:3000
Lenguaje del código: PHP (php)/api/health.En producción, lo razonable es frontal con Nginx, HTTPS con Let’s Encrypt, y alertas sobre health/status (Prometheus + Alertmanager, Uptime Kuma, Statuscake, etc.). Para trazabilidad, canalizar logs de PM2/Docker/Nginx a ELK/EFK o Loki.
Buenas prácticas (imprescindibles):
HeadlessX aporta la base técnica; la responsabilidad del uso (ético y legal) es de cada organización.
La reestructuración separa rutas → controladores → servicios → middleware → utils → config. Los servicios de browser, stealth, interaction y rendering encapsulan lógica compleja; los middleware de auth y error centralizan seguridad y manejo de fallos; logger.js unifica formato y permite correlación entre peticiones.
Esta división facilita:
n8n-nodes-headlessx): pipelines low-code para scraping + transformación + envío a DB/Sheets/CRM.Este enfoque convierte a HeadlessX en un eslabón estándar dentro de flujos ETL/ELT o RPA web.
HeadlessX v1.2.0 encaja donde un navegador headless autogestionado tiene sentido: equipos que necesitan control total, coste predecible, trazabilidad y comportamiento humano para maximizar la entrega de datos respetando límites técnicos y normativos. Su combinación de Docker/PM2, logs estructurados, endpoints claros y arquitectura modular lo hacen especialmente atractivo para operaciones de scraping serias que busquen estabilidad de plataforma y velocidad de evolución.
Quien ya trabaja con Playwright o Browserless encontrará aquí un punto de equilibrio entre ligereza, control y capacidad de producción. Y quien empiece desde cero, tiene una rampa de acceso muy corta para poner en marcha, con seguridad y buenos modales, un servidor de web scraping “humano”.
¿En qué se diferencia de Browserless o de lanzar Playwright a pelo?
Ofrece un servidor listo con API unificada, antidetención avanzada, comportamiento humano, autenticación, rate limit, logs correlacionados y artefactos (PDF/PNG). Es más “plataforma” que librería.
¿Cómo se protege en producción?
Autenticación por token, rate limiting en Nginx, headers de seguridad, SSL/TLS, salud (/api/health) y estado (/api/status). Recomendable añadir WAF/CDN, monitorización y centralización de logs.
¿Puedo integrarlo sin programar?
Sí. n8n, Make y Zapier permiten montar flujos de scraping → limpieza → entrega (DB, hojas de cálculo, CRMs) con pocos clics usando los endpoints HTTP.
¿Qué límites debo considerar para escalar?
MAX_CONCURRENT_BROWSERS).Repositorio en GitHub. Si se despliega, conviene comenzar con Docker, ajustar AUTH_TOKEN, probar health/status, y activar SSL antes de abrir el endpoint a terceros.
