escalator

URLを渡すと、クリーンなMarkdownが返ってきます。動作する最も安いラン段を登っていきます — 素のHTTPフェッチ、同じフェッチを住宅用プロキシ経由で、そしてステルスブラウザ — そして実際のコンテンツが返ってきた最初の段で停止します。

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

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

クイックスタート

# 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

それがオンボーディングの全体です。init が設定ファイルを1つ書き出し、初回実行前に手で編集する必要はありません。何かおかしい場合は: escalator doctor。

最小限のLinuxでは（ベアコンテナ、新しいVPS）、Chromeはデスクトップがすでに持っているシステムライブラリを必要とします。escalatorはそれらをインストールしません — 正確な apt-get の行を表示し、escalator doctor がそれを繰り返します。1回だけ、1コマンド:

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

設計上、バッテリーは同梱しません。 escalatorは未設定のまま出荷されます — ブラウザの同梱なし、プロキシの同梱なし、テレメトリなし、自身のディレクトリの外には何も書き込みません。init は、設定をREADMEの宝探しではなく2分の会話にするために存在します。

Related MCP server: Safer Fetch MCP Server

インストール

コアフローに必要なものはすべてデフォルトインストールに含まれています。ブラウザのラン段も含めて — ブラウザは同梱されず、それが escalator browser install の役割です。追加が1つあります: escalator[mcp] がMCPインターフェースを追加し、Dockerイメージにはそれが含まれています。

Docker

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

イメージには固定されたブラウザが含まれ、環境変数だけで完全に設定されます — プロキシの配線については docker-compose.example.yml を参照してください。uid 1000 で実行されるため、バインドマウントされた ./data はその uid から書き込み可能である必要があります。

コマンド

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

ラダー

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.

これが単なる for ループ以上のものになるのは2つの点です:

200 OK は成功ではありません。 Cloudflareのインタースティシャルを伴うHTTP 200を返すラン段は成功していません。core/detect.py は抽出後にすべてのレスポンスを分類します — content、thin、blocked — そして content だけが有効です。それがなければラダーは決してエスカレーションせず、キャッシュはジャンクを永遠に配信するドメインに対して「httpが機能する」と学習してしまいます。

キャッシュは忘れます。 学習された開始ラン段が上にしかラチェットしないと、すべてのドメインがブラウザ+プロキシへと漂い、プロキシ料金を静かに膨らませます。エントリは learned_at を保持します。ladder.tier_cache_ttl_hours を過ぎると、ドメインは1段安いラン段を再試行します。

なぜこの形になっているのか、そして意図的に何を拒否しているのかは DESIGN.md を参照してください。

設定

init によって書き込まれる1つのファイルで、プラットフォームの設定ディレクトリにあります（Linuxでは ~/.config/escalator/config.toml、macOSでは ~/Library/Application Support/escalator/config.toml）。場所は --config で上書きできます。

優先順位は、どこでも:

CLI flag  >  environment  >  config.toml  >  default

すべてのキーには環境変数があり、それがファイルがまったく存在しなくてもDockerイメージが設定される方法です:

データ — SQLiteデータベースとダウンロードされたブラウザ — はプラットフォームのデータディレクトリに置かれ、ESCALATOR_STORAGE_DATA_DIR で上書きできます。その外には何も書き込まれません。

ブラウザの入手先

escalator browser list は検索を順に表示します:

1. 明示的なパス — --browser-path、次に ESCALATOR_BROWSER_PATH、次に browser.path。設定されていて間違っている場合は、パスを指定したエラーになります。黙ってフォールスルーすることはありません。

2. このマシンにインストールされているブラウザ: 本物のGoogle Chromeが最初、次にChromium、次にEdgeとBrave。

3. 以前に escalator browser install がダウンロードしたブラウザ。

どれも見つからない場合は、それを修正する2つのコマンドを指定したエラーが表示されます。解決は自動でダウンロードしません — サーバーリクエストやcronジョブが副作用としてソフトウェアをインストールすべきではありません。

サーバーの使用

escalator serve   # 127.0.0.1:8000 by default

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

Authorization: Bearer <key> で認証します。ここで key は server.api_keys の1つです。そのリスト が 真実です：キーを削除すると、次の起動時に失効されます。新しいキーを発行するエンドポイントはありません。

壁はHTTPエラーではなく、200 OK と {"status": "challenged"} で返ってきます。これは意図的です：エージェントの側がそれに反応できるように。ループで再試行しても役に立ちません — escalatorは設計上CAPTCHAを解決しません。

[mcp] エクストラを使用すると、同じラダーが /mcp で1つのツールとして公開されます: scrape_url(url, force_browser=False)。

トラブルシューティング

まずここから:

escalator doctor

Python、設定ファイル、データディレクトリ、ブラウザの解決、実際のヘッドレス起動、そして — プロキシが設定されている場合 — それを通した1回の実際のリクエストをチェックし、パスワードをマスクした状態で出口のIPと国を報告します。すべての❌にはそれを修正する1行が付属し、何かが失敗した場合は終了コードが非ゼロになるため、スクリプトでも使用できます。マシン向けには escalator doctor --json。

それでも動作しない場合は、escalator doctor の出力全体をissueに貼り付けてください — それがその最後の行が求めているものであり、回答への最速の道です。

開発

CONTRIBUTING.md を参照してください。要するに: uv sync、uv run pytest。

ライセンス

パブリックドメインとして公開されています — UNLICENSE を参照してください。保証なし、帰属表示不要、好きなように使ってください。