# Instrucciones para el agente: HeadlessX: autoaloja extracción y automatización web

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: avanzado
- Proyecto: https://github.com/saifyxpro/HeadlessX (licencia NOASSERTION)
- Guía completa: https://lab.wisd.ai/hub/headlessx-browser-platform

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

Comprueba los requisitos de desarrollo: Node.js ≥22.20.0, npm/npx, pnpm ≥10.32.1, Git, Docker con Compose v2 en marcha, Python ≥3.12 con uv y Go ≥1.26.0. El mínimo de Node cubre [skills](https://github.com/vercel-labs/skills/blob/main/package.json); los de Python y Go salen de [yt-engine](https://github.com/saifyxpro/HeadlessX/blob/main/apps/yt-engine/pyproject.toml) y [la conversión HTML](https://github.com/saifyxpro/HeadlessX/blob/main/apps/go-html-to-md-service/go.mod). Reserva al menos 2 núcleos, 4 GB de RAM y 10 GB de disco libre. La vía guiada para agentes instala esta skill:

```sh
npx skills add https://github.com/saifyxpro/HeadlessX --skill cli
```

La skill no instala la plataforma. Instala la CLI con el comando del README y usa el asistente de la versión actual:

```sh
npm install -g @headlessx-cli/core
```

Consulta [la guía de autoalojamiento](https://headlessx.saify.me/docs/self-hosting/overview). El README de v2.1.2 documenta:

```sh
headlessx init --mode developer
```

Una vez terminado el asistente, comprueba `headlessx status` y `headlessx doctor`. Para conectar la CLI al servicio, ejecuta `headlessx login --api-url http://localhost:38473` e introduce de forma privada una clave de HeadlessX de tu instalación cuando la solicite. Usa la dirección que haya configurado el asistente si cambiaste el puerto. El [README de la CLI](https://github.com/saifyxpro/HeadlessX/blob/main/packages/cli/README.md#authentication) documenta juntos clave y destino.

Prueba su comando de extracción:

```sh
headlessx scrape https://example.com
```

Debe recuperar el contenido de Example Domain. Empieza en desarrollo antes de preparar dominios de producción. El [código de la CLI](https://github.com/saifyxpro/HeadlessX/blob/main/packages/cli/src/utils/lifecycle.ts) distingue `developer` (servicios de aplicación en el host), `self-host` (pila Docker local) y `production` (Docker y dominios). Elige una ruta; la guía de montaje desarrolla sobre todo `self-host`.

## Comprobación

Ejecuta una extracción de una página de prueba con el ejemplo de la API oficial. Compara el contenido y revisa qué servicio recibe las peticiones.

## Si algo falla

Si el navegador falla, comprueba dependencias y recursos del contenedor. Si el cliente no conecta, revisa dirección, autenticación y configuración del servicio.

Consulta [el README oficial](https://github.com/saifyxpro/HeadlessX#readme) para requisitos y variantes de instalación.