escalator

Dale una URL, obtén Markdown limpio. Sube por el peldaño más barato que funcione — una petición HTTP simple, la misma petición a través de un proxy residencial, y luego un navegador sigiloso — y se detiene en el primero que devuelva contenido real.

$ escalator scrape https://en.wikipedia.org/wiki/Web_scraping | head -3
# Web scraping

**Web scraping**, **web harvesting**, or **web data extraction** is [data scraping](...)

Quickstart

# 1. install uv (https://docs.astral.sh/uv/getting-started/installation/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. configure this machine -- finds your browser, or fetches one
uvx escalator init

# 3. use it
uvx escalator scrape https://en.wikipedia.org/wiki/Web_scraping

Eso es toda la rampa de entrada. init escribe un archivo de configuración, y no hay que editar nada a mano antes de la primera ejecución. Si algo parece mal: escalator doctor.

En un Linux mínimo (un contenedor desnudo, un VPS nuevo) Chrome necesita bibliotecas del sistema que un escritorio ya tiene. escalator no las instala por ti — imprime la línea exacta de apt-get y escalator doctor la repite. Un comando, una vez:

sudo apt-get update && sudo apt-get install -y \
  libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
  libgbm1 libglib2.0-0t64 libpango-1.0-0 libcairo2 libasound2t64 \
  libatspi2.0-0t64 libxcb1 libdbus-1-3 libexpat1

Sin baterías, por diseño. escalator viene sin configurar — sin navegador incluido, sin proxies incluidos, sin telemetría, nada escrito fuera de sus propios directorios. init existe para que configurarlo sea una conversación de dos minutos en lugar de una búsqueda del tesoro en el README.

Related MCP server: Safer Fetch MCP Server

Installation

Todo lo necesario para el flujo principal está en la instalación predeterminada, incluido el peldaño del navegador — no trae ningún navegador consigo, para eso está escalator browser install. Existe un extra: escalator[mcp] añade la cara MCP, y la imagen Docker lo incluye.

Docker

docker run --rm \
  -e ESCALATOR_SERVER_API_KEYS=your-key \
  -p 8000:8000 -v ./data:/data \
  ghcr.io/ruslanstarikov/escalator serve

La imagen lleva un navegador fijado y se configura enteramente mediante variables de entorno — consulta docker-compose.example.yml para el cableado del proxy. Se ejecuta como uid 1000, por lo que un ./data montado por bind debe ser escribible por él.

Commands

escalator init [--yes]     configure this machine; --yes for scripts
escalator doctor [--json]  check everything, one fix per failure
escalator browser list     every browser found, and which one wins
escalator browser install  download Chrome for Testing into the data dir
escalator scrape URL       one page to stdout, so it pipes
escalator serve            the HTTP API and the MCP face
escalator --version        tool, python, platform

The ladder

policy      robots.txt (cached) + rate limit  → may short-circuit (skip/deny/wait)
http        curl_cffi, impersonate=chrome     → ~100ms; clears undefended sites
http_proxy  same, routed via residential IP   → beats datacenter-IP bans
browser     nodriver, headless Chrome         → JS/SPA + Cloudflare-class defenses
                    │
                    └─ walled on the last rung? → status="challenged". Surrender.

Dos cosas hacen que esto sea más que un bucle for:

200 OK no es éxito. Un peldaño que devuelve HTTP 200 con un intersticial de Cloudflare no ha tenido éxito. core/detect.py clasifica cada respuesta después de la extracción — content, thin o blocked — y solo content cuenta. Sin eso, la escalera nunca escalaría, y la caché aprendería "http funciona" para un dominio que sirve basura para siempre.

La caché olvida. Un peldaño inicial aprendido que solo subiera de nivel haría que cada dominio derivara hacia navegador+proxy e inflaría silenciosamente tu factura de proxy. Las entradas llevan learned_at; pasado ladder.tier_cache_ttl_hours, un dominio reintenta un peldaño más barato.

Consulta DESIGN.md para saber por qué tiene esta forma — y para lo que deliberadamente se niega a hacer.

Configuration

Un archivo, escrito por init, en el directorio de configuración de la plataforma (~/.config/escalator/config.toml en Linux, ~/Library/Application Support/escalator/config.toml en macOS). Sobrescribe la ubicación con --config.

Precedencia, en todas partes:

CLI flag  >  environment  >  config.toml  >  default

Cada clave tiene una variable de entorno, que es como se configura la imagen Docker sin que exista ningún archivo:

Los datos — la base de datos SQLite y cualquier navegador descargado — viven en el directorio de datos de la plataforma, que se puede sobrescribir con ESCALATOR_STORAGE_DATA_DIR. Nunca se escribe nada fuera de él.

Where the browser comes from

escalator browser list muestra la búsqueda, en orden:

1. una ruta explícita — --browser-path, luego ESCALATOR_BROWSER_PATH, luego browser.path. Si está configurada y es incorrecta, es un error que nombra la ruta, nunca una caída silenciosa.

2. navegadores instalados en esta máquina: Google Chrome real primero, luego Chromium, luego Edge y Brave.

3. un navegador que escalator browser install descargó anteriormente.

Si ninguno de esos encuentra algo, obtienes un error que nombra los dos comandos que lo arreglan. La resolución nunca descarga por sí sola — una petición de servidor o un trabajo cron no debería instalar software como efecto secundario.

Using the server

escalator serve   # 127.0.0.1:8000 by default

POST /scrape   {url, markdown?, min_tier?, max_tier?, timeout_ms?}  -> FetchResult
GET  /healthz                                                       -> {status, version}

Autentica con Authorization: Bearer <key>, donde la clave es una de server.api_keys. Esa lista es la verdad: elimina una clave y se revoca en el próximo inicio. No hay endpoint para acuñar una.

Un muro devuelve 200 OK con {"status": "challenged"}, no como un error HTTP. Eso es deliberado: un agente al otro lado puede reaccionar. Reintentar en bucle no ayudará — escalator no resuelve CAPTCHAs, por diseño.

Con el extra [mcp], la misma escalera se expone en /mcp como una herramienta, scrape_url(url, force_browser=False).

Troubleshooting

Empieza aquí:

escalator doctor

Comprueba Python, el archivo de configuración, el directorio de datos, la resolución del navegador, un lanzamiento headless real y — si hay un proxy configurado — una petición real a través de él, informando la IP de salida y el país con la contraseña enmascarada. Cada ❌ viene con la línea que lo arregla, y el código de salida es distinto de cero si algo falla, para que los scripts también puedan usarlo. escalator doctor --json para máquinas.

Si aún no funciona, pega la salida completa de escalator doctor en un issue — eso es lo que pide su última línea, y es la ruta más rápida a una respuesta.

Development

Consulta CONTRIBUTING.md. En resumen: uv sync, uv run pytest.

License

Publicado en el dominio público — consulta UNLICENSE. Sin garantía, sin atribución requerida, haz lo que quieras con él.