escalator

Gib ihm eine URL, erhalte sauberes Markdown. Es klettert die günstigste Sprosse, die funktioniert – ein einfacher HTTP-Abruf, derselbe Abruf über einen Residential-Proxy, dann ein Stealth-Browser – und stoppt bei der ersten, die mit echtem Inhalt zurückkommt.

$ 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

Das ist die gesamte Einstiegshilfe. init schreibt eine Konfigurationsdatei, und vor dem ersten Lauf muss nichts von Hand bearbeitet werden. Wenn etwas falsch aussieht: escalator doctor.

Auf einem minimalen Linux (einem nackten Container, einem frischen VPS) benötigt Chrome Systembibliotheken, die ein Desktop bereits hat. escalator installiert sie nicht für dich – es gibt die genaue apt-get-Zeile aus, und escalator doctor wiederholt sie. Ein Befehl, einmal:

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

Keine Batterien, by design. escalator wird unkonfiguriert ausgeliefert – kein gebündelter Browser, keine gebündelten Proxys, keine Telemetrie, nichts wird außerhalb seiner eigenen Verzeichnisse geschrieben. init existiert, damit die Konfiguration ein Zwei-Minuten-Gespräch ist und keine README-Schnitzeljagd.

Related MCP server: Safer Fetch MCP Server

Installation

Alles, was für den Kernablauf benötigt wird, ist in der Standardinstallation enthalten, einschließlich der Browser-Sprosse – sie bringt keinen Browser mit, wofür escalator browser install gedacht ist. Ein Extra existiert: escalator[mcp] fügt die MCP-Oberfläche hinzu, und das Docker-Image enthält sie.

Docker

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

Das Image enthält einen festgelegten Browser und wird vollständig über Umgebungsvariablen konfiguriert – siehe docker-compose.example.yml für die Proxy-Verdrahtung. Es läuft als UID 1000, daher muss ein bind-gemountetes ./data für es beschreibbar sein.

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.

Zwei Dinge machen das mehr als eine for-Schleife:

200 OK ist kein Erfolg. Eine Sprosse, die HTTP 200 mit einer Cloudflare-Zwischenseite zurückgibt, ist nicht erfolgreich. core/detect.py klassifiziert jede Antwort nach der Extraktion – content, thin oder blocked – und nur content zählt. Ohne das würde die Leiter nie eskalieren, und der Cache würde für eine Domain, die für immer Müll ausliefert, lernen, dass „http funktioniert“.

Der Cache vergisst. Eine gelernte Startsprosse, die nur nach oben klettert, würde jede Domain in Richtung Browser+Proxy treiben und deine Proxy-Rechnung leise aufblähen. Einträge tragen learned_at; nach ladder.tier_cache_ttl_hours versucht eine Domain eine Sprosse günstiger erneut.

Siehe DESIGN.md für den Grund, warum es so geformt ist – und für das, was es bewusst ablehnt zu tun.

Configuration

Eine Datei, geschrieben von init, im Plattform-Konfigurationsverzeichnis (~/.config/escalator/config.toml unter Linux, ~/Library/Application Support/escalator/config.toml unter macOS). Überschreibe den Speicherort mit --config.

Priorität, überall:

CLI flag  >  environment  >  config.toml  >  default

Jeder Schlüssel hat eine Umgebungsvariable, so wird das Docker-Image konfiguriert, ohne dass überhaupt eine Datei existiert:

Daten – die SQLite-Datenbank und jeder heruntergeladene Browser – leben im Plattform-Datenverzeichnis, überschreibbar mit ESCALATOR_STORAGE_DATA_DIR. Außerhalb davon wird nie etwas geschrieben.

Where the browser comes from

escalator browser list zeigt die Suche in dieser Reihenfolge:

1. ein expliziter Pfad – --browser-path, dann ESCALATOR_BROWSER_PATH, dann browser.path. Wenn er gesetzt und falsch ist, ist das ein Fehler, der den Pfad nennt, niemals ein stilles Durchfallen.

2. auf diesem Rechner installierte Browser: zuerst echtes Google Chrome, dann Chromium, dann Edge und Brave.

3. ein Browser, den escalator browser install früher heruntergeladen hat.

Wenn keiner davon etwas findet, erhältst du einen Fehler, der die beiden Befehle nennt, die das beheben. Die Auflösung lädt nie von selbst herunter – eine Serveranfrage oder ein Cron-Job sollte keine Software als Nebeneffekt installieren.

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}

Authentifiziere dich mit Authorization: Bearer <key>, wobei der Schlüssel einer aus server.api_keys ist. Diese Liste ist die Wahrheit: Entferne einen Schlüssel, und er wird beim nächsten Start widerrufen. Es gibt keinen Endpunkt, um einen zu erstellen.

Eine Wand kommt als 200 OK mit {"status": "challenged"} zurück, nicht als HTTP-Fehler. Das ist beabsichtigt: Ein Agent am anderen Ende kann darauf reagieren. Wiederholen in einer Schleife hilft nicht – escalator löst keine CAPTCHAs, by design.

Mit dem [mcp]-Extra wird dieselbe Leiter unter /mcp als ein Werkzeug bereitgestellt, scrape_url(url, force_browser=False).

Troubleshooting

Beginne hier:

escalator doctor

Es prüft Python, die Konfigurationsdatei, das Datenverzeichnis, die Browser-Auflösung, einen tatsächlichen Headless-Start und – wenn ein Proxy konfiguriert ist – eine echte Anfrage durch ihn, wobei die Egress-IP und das Land mit maskiertem Passwort gemeldet werden. Jedes ❌ wird mit der einen Zeile geliefert, die es behebt, und der Exit-Code ist ungleich Null, wenn etwas fehlgeschlagen ist, sodass Skripte es ebenfalls verwenden können. escalator doctor --json für Maschinen.

Wenn es immer noch nicht funktioniert, füge die gesamte escalator doctor-Ausgabe in ein Issue ein – genau das verlangt die letzte Zeile davon, und es ist der schnellste Weg zu einer Antwort.

Development

Siehe CONTRIBUTING.md. Kurz: uv sync, uv run pytest.

License

In die Public Domain entlassen – siehe UNLICENSE. Keine Garantie, keine Namensnennung erforderlich, mach damit, was du willst.