- Data residency or network isolation - air-gapped environments, on-premise deployments, strict compliance
- A custom fork - you want to modify scraping behavior, add new engines, or ship patches to your own version
- Extreme volume - your workload is high enough that infrastructure costs beat API credits
reader on GitHub →
Full source, issues, Dockerfile, and examples.
Cloud vs Self-Hosted
| Feature | Reader Cloud | Self-hosted |
|---|---|---|
| Setup time | Instant (sign up + API key) | Install Node, configure proxies, manage browsers |
| Proxies | Managed pool included | You provide your own |
| Cost model | Monthly credits (free tier: 1,000/mo) | Your infrastructure |
| Webhooks | Built-in | Build your own |
| SSE events | Built-in | Build your own |
| Scaling | Automatic | You manage it |
| Updates | Automatic | npm update |
| Support | Discord + email | Community (GitHub) |
| Best for | Shipping apps fast, LLM pipelines, RAG, agents | Compliance, isolation, custom forks, extreme volume |
What self-hosted Reader gives you
ReaderClient- high-level API with lazy initialization, browser pool management, and proxy rotationscrape()andcrawl()- the same primitives as the Cloud API- Hero browser engine - full headless Chrome with JavaScript execution, TLS fingerprinting, and anti-bot bypass
- Proxy escalation - automatic datacenter-to-residential failover per URL
- Browser pool - recycled Hero instances with health checks and graceful retirement
- CLI - one-off scrapes, crawls, and a daemon mode with shared pool
- Pluggable config - domain profiles, block detection, and URL rewriters are all caller-provided
- Deployment scripts - production-ready Dockerfile and Docker Compose setup
Where to go next
Installation
Install the package and its system dependencies.
Quickstart
Make your first scrape in 60 seconds.
Examples
Real runnable examples for every feature.
API Reference
Full type reference for every option and result.