escalator

URL을 주면 깨끗한 Markdown을 돌려줍니다. 작동하는 가장 저렴한 단계를 오릅니다 — 일반 HTTP fetch, 동일한 fetch를 주거용 프록시를 통해, 그다음 스텔스 브라우저 — 그리고 실제 콘텐츠가 돌아오는 첫 번째 단계에서 멈춥니다.

$ 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

이것이 전체 온램프입니다. init은 구성 파일 하나를 작성하며, 첫 실행 전에 수동으로 편집할 필요가 없습니다. 뭔가 잘못된 것 같으면: escalator doctor.

최소 Linux에서 (베어 컨테이너, 새 VPS) Chrome은 데스크톱에 이미 있는 시스템 라이브러리가 필요합니다. escalator는 이를 설치해 주지 않습니다 — 정확한 apt-get 명령을 출력하고 escalator doctor가 이를 반복합니다. 명령 하나, 한 번만:

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

Installation

핵심 흐름에 필요한 모든 것은 기본 설치에 포함되어 있으며, 브라우저 단계도 포함됩니다 — 브라우저를 함께 가져오지는 않으며, 그것이 escalator browser install의 용도입니다. 추가 기능이 하나 있습니다: 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는 해당 사용자가 쓸 수 있어야 합니다.

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.

이것을 단순한 for 루프 이상으로 만드는 두 가지가 있습니다:

200 OK는 성공이 아닙니다. Cloudflare 중간 페이지를 담은 HTTP 200을 반환하는 단계는 성공한 것이 아닙니다. core/detect.py는 추출 후 모든 응답을 content, thin, blocked로 분류하며, content만 인정됩니다. 이것이 없으면 사다리는 결코 단계를 올리지 않을 것이고, 캐시는 쓰레기를 영원히 제공하는 도메인에 대해 "http가 작동한다"고 학습할 것입니다.

캐시는 잊습니다. 위로만 올라가는 학습된 시작 단계는 모든 도메인을 브라우저+프록시 쪽으로 밀어내고 조용히 프록시 비용을 부풀릴 것입니다. 항목은 learned_at을 가지며, ladder.tier_cache_ttl_hours가 지나면 도메인은 한 단계 더 저렴한 단계를 다시 시도합니다.

이렇게 설계된 이유와 의도적으로 거부하는 것에 대해서는 DESIGN.md를 참조하세요.

Configuration

하나의 파일, init이 작성하며, 플랫폼 구성 디렉터리에 있습니다 (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로 재정의할 수 있습니다. 그 외부에는 아무것도 쓰이지 않습니다.

Where the browser comes from

escalator browser list는 검색 순서를 보여줍니다:

1. 명시적 경로 — --browser-path, 그다음 ESCALATOR_BROWSER_PATH, 그다음 browser.path. 설정되어 있지만 잘못된 경우, 경로를 명시하는 오류가 발생하며 조용히 넘어가지 않습니다.

2. 이 머신에 설치된 브라우저: 실제 Google Chrome 먼저, 그다음 Chromium, 그다음 Edge와 Brave.

3. 이전에 escalator browser install로 다운로드한 브라우저.

이 중 아무것도 찾지 못하면, 문제를 해결하는 두 명령을 명시하는 오류가 발생합니다. 해결은 자체적으로 다운로드하지 않습니다 — 서버 요청이나 cron 작업이 부작용으로 소프트웨어를 설치해서는 안 됩니다.

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}

Authorization: Bearer <key>로 인증하며, 키는 server.api_keys 중 하나입니다. 그 목록이 진실입니다: 키를 제거하면 다음 시작 시 폐기됩니다. 새 키를 발급하는 엔드포인트는 없습니다.

벽은 HTTP 오류가 아닌 200 OK와 {"status": "challenged"}로 돌아옵니다. 이는 의도적입니다: 상대편의 에이전트가 이에 반응할 수 있습니다. 루프로 재시도해도 도움이 되지 않습니다 — escalator는 설계상 CAPTCHA를 해결하지 않습니다.

[mcp] 추가 기능을 사용하면 동일한 사다리가 /mcp에서 하나의 도구 scrape_url(url, force_browser=False)로 노출됩니다.

Troubleshooting

여기서 시작하세요:

escalator doctor

Python, 구성 파일, 데이터 디렉터리, 브라우저 해석, 실제 헤드리스 실행, 그리고 프록시가 구성된 경우 프록시를 통한 실제 요청 하나를 확인하며, 비밀번호를 마스킹한 채 이그레스 IP와 국가를 보고합니다. 모든 ❌에는 문제를 해결하는 한 줄이 함께 제공되며, 실패한 것이 있으면 종료 코드가 0이 아니므로 스크립트에서도 사용할 수 있습니다. 머신용으로는 escalator doctor --json.

그래도 작동하지 않으면 escalator doctor 출력 전체를 이슈에 붙여넣으세요 — 그것이 마지막 줄이 요청하는 것이며, 답을 얻는 가장 빠른 경로입니다.

Development

CONTRIBUTING.md를 참조하세요. 요약: uv sync, uv run pytest.

License

퍼블릭 도메인으로 공개됨 — UNLICENSE 참조. 보증 없음, 저작자 표시 불필요, 원하는 대로 사용하세요.