# TRAWL — self-hosted FlareSolverr/Byparr replacement

Verified 13.10.2026: repo https://github.com/germondai/trawl (200), site https://trawl.germondai.com (200), docs https://docs.trawl.germondai.com (200). 979 stars, 59 forks, AGPL-3.0, v1.8.0 (08.10.2026), 582 commits, active dev.

## Что это

Self-hosted scraping engine. Заменяет мёртвый FlareSolverr и Byparr. Стек: Bun + Elysia (API), Redis 8.8 (session cache), Camoufox Firefox (browser automation, fingerprint-patched на C++/Juggler уровне), Nuxt 4 (UI), VitePress (docs). Monorepo: apps/ + packages/.

## Пробиваемые защиты (всё локально, без платных solver-API)

- Cloudflare: Turnstile, Interstitial/JS challenge
- Akamai Bot Manager
- Imperva / Incapsula
- GeeTest Slide
- Friendly Captcha v1/v2
- ALTCHA
- CAP proof-of-work
- reCAPTCHA v2 — бесплатный audio через локальный Whisper (STT_URL env)
- hCaptcha checkbox/audio where available
- Опциональный fallback: 2Captcha (reCAPTCHA v2/Enterprise, standalone Turnstile)

## 4-уровневая эскалация (tier pipeline)

1. Tier 0: plain HTTP fetch (мгновенно)
2. Tier 1: cached browser session из Redis (переиспользует решённые cookies + browser identity)
3. Tier 2: fresh challenge solve в Camoufox
4. Tier 3/4: (residential) proxy escalation — PROXY_LIST_FILE / RESIDENTIAL_PROXY_URL

## Деплой

```bash
git clone https://github.com/germondai/trawl
cd trawl
cp .env.example .env
docker compose up -d
curl http://localhost:8191/health
```

Первый старт 15-30с (browser pool warmup). Есть docker-compose.minimal.yml и docker-compose.prod.yml. One-click в каталогах TrueNAS (apps.truenas.com/catalog/trawl_community) и Unraid (ca.unraid.net/apps/trawl-1o4q23p06utr4h).

## API

FlareSolverr-compatible (drop-in для Prowlarr/Jackett/Sonarr/*arr):

```bash
curl -X POST http://localhost:8191/v1 \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"request.get","url":"https://nowsecure.nl","maxTimeout":60000}'
```

Native API (богатая мета: tier, timings, sessionCached, полный список cookies):

```bash
curl -X POST http://localhost:8191/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://nowsecure.nl","maxTimeout":60000}'
```

В Prowlarr: FlareSolverr URL = http://localhost:8191 (или http://trawl:8191 в compose-сети).

## MCP для AI-агентов

MCP_ENABLED=true → Streamable HTTP MCP-сервер на /mcp. Инструменты: чтение страниц как Markdown/text, scrape HTML, extract JSON records, screenshots (viewport/full-page/element), browser diagnostics. Грузит только известные публичные URL — web search НЕ даёт.

## Isolated browser sessions

Сохраняют login cookies и localStorage между native API / MCP / FlareSolverr запросами, capacity limits + auto idle expiry. Session API: docs.trawl.germondai.com/api-reference/browser-sessions

## MITM challenge-bypass proxy

Для сайтов, где CF clearance привязан к полному connection fingerprint (cookie не переносится — Prowlarr re-fetch своим клиентом ловит re-challenge):

```env
MITM_ENABLED=true
MITM_PORT=8192
MITM_CA_DIR=/data/proxy-ca   # персист CA (volume)
MITM_MAX_TIER=4              # cap эскалации (3 = без residential)
MITM_ALWAYS_SCRAPE=false
MITM_HOST=0.0.0.0            # 127.0.0.1 для loopback-only
```

CA: `curl http://<host>:8191/proxy-ca.crt` → в trust store клиента. Prowlarr: Settings → Indexer Proxies → HTTP, порт 8192. Обычный трафик идёт direct; HTML/JSON/text буферизуются для challenge detection; видео/бинари стримятся; Range/206 end-to-end; WebSocket direct relay. ВНИМАНИЕ: MITM может impersonate любой хост — только private interface.

## Ключевые env

| Var | Default | Назначение |
|-----|---------|-----------|
| PORT | 8191 | API |
| STT_URL | — | локальный Whisper для reCAPTCHA audio |
| PROXY_LIST_FILE | — | Tier 3 proxy URLs (по строке) |
| RESIDENTIAL_PROXY_URL | — | включает Tier 4 |
| MCP_ENABLED | false | MCP-сервер |
| MITM_* | см. выше | forward proxy |

Полная таблица — README apps/docs/getting-started/configuration.md. При апгрейде со старых версий — migration guide (переименования env, Redis opt-in).

## Ключевые файлы репы

- apps/docs/integrations/mcp.md — MCP-интеграция
- apps/docs/proxy/overview.md — прокси-маршрутизация, CA, примеры клиентов
- apps/docs/deployment/configuration-migration.md — миграция env
- .env.example — полный список переменных

## Отношение к нашему стеку

- Camoufox у нас уже используется (BrowserMCP, SearchMCP, abliteration farm, conol) — знакомый runtime, те же pitfall'ы (geoip, launch timeout, SWGL crash — см. memory Camoufox pitfalls)
- Конкурент Tier 2 CloudflareBypassForScraping (sarperavci): TRAWL быстрее под нагрузкой (Redis session reuse), мульти-WAF, MCP из коробки, но требует Docker + Redis (тяжелее)
- Для *arr и постоянного парсинга — TRAWL; для разового скрипта — curl_cffi/CloakBrowser по-прежнему легче
- Бенчмарки авторов: trawl.germondai.com/#compare (same-machine, быстрее FlareSolverr и Byparr; результаты зависят от сайта/сессии)
- Спонсоры README: Bright Data, NodeMaven (промо TRAWL35/TRAWL40), Thordata (TRAWL10) — жилые прокси для Tier 4, если понадобятся