What is html2rss?

html2rss-web is a self-hosted web application that transforms webpages into RSS 2.0 or JSON feeds. Users enter a URL in the browser interface and the auto-source feature pulls feed items without manual selector creation. A companion botasaurus-scrape-api service processes JavaScript-heavy sites. The same deployment also provides a Feed Directory catalog. It runs via Docker Compose with the main web app on port 4000 and the scraper on port 4010. Configuration relies on environment variables for required secrets such as session encryption and access tokens. Capabilities include automatic feed creation, Feed Directory API, custom YAML feed mounting, OpenAPI documentation, health check endpoints, rate limiting, and optional Sentry integration. The project uses the MIT license and receives regular releases.

Should you self-host html2rss?

html2rss scores 50/100 on selfhost.directory (how scoring works) and ranks #27 of 85 in Feed Reader. It has 194 GitHub stars.

It shipped 19 stable releases in the past year. The latest, v1.14.5, came out on 23 October 2026. New versions land roughly every 1 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Ruby.

Its closest alternative on selfhost.directory is RSSHub (85/100, 46 703 stars). It scores higher overall, so compare the two before you pick. See html2rss vs RSSHub side by side.

Features

Access token authentication
Automatic feed generation from URL
Custom YAML feeds
Feed Directory catalog
Health endpoints
JavaScript rendering support
OpenAPI documentation
Rate Limiting
RSS 2.0 and JSON Feed output
Sentry Integration

How to configure html2rss

ASYNC_FEED_REFRESH_ENABLEDfalseOptional boolean; default false
Optional boolean; default false
values: true/false
ASYNC_FEED_REFRESH_STALE_FACTOR3Optional integer >= 1; default 3
Optional integer >= 1; default 3
AUTO_SOURCE_ENABLEDtrueKeep enabled to allow pasting any webpage URL to generate an RSS feed.
Keep enabled to allow pasting any webpage URL to generate an RSS feed.
values: true/false
BOTASAURUS_SCRAPER_URLhttp://botasaurus:4010URL of the companion Botasaurus scraper API service in docker-compose.
URL of the companion Botasaurus scraper API service in docker-compose.
BOTASAURUS_SCRAPE_TIMEOUT_SECONDS45Optional; HTTP client cap for POST /scrape in seconds; default 45; mirrors SCRAPE_TIMEOUT_SECONDS on botasaurus-scrape-api
Optional; HTTP client cap for POST /scrape in seconds; default 45; mirrors SCRAPE_TIMEOUT_SECONDS on botasaurus-scrape-api
BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS30Optional; maximum wait_timeout_seconds in feed YAML; default 30; mirrors SCRAPE_WORK_TIMEOUT_SECONDS on botasaurus-scrape-api
Optional; maximum wait_timeout_seconds in feed YAML; default 30; mirrors SCRAPE_WORK_TIMEOUT_SECONDS on botasaurus-scrape-api
BOTASAURUS_SENTRY_DSNOptional; separate Sentry DSN for botasaurus-scrape-api
Optional; separate Sentry DSN for botasaurus-scrape-api
FEEDS_CACHE_MAX_SIZE500Optional integer >= 1; default 500; maximum number of feeds to cache in memory before eviction
Optional integer >= 1; default 500; maximum number of feeds to cache in memory before eviction
HEALTH_CHECK_TOKENOptional bearer token for authenticated GET /api/v1/health; not part of the first-run quickstart; use /api/v1/health/ready for standard readiness checks
Optional bearer token for authenticated GET /api/v1/health; not part of the first-run quickstart; use /api/v1/health/ready for standard readiness checks
HTML2RSS_ACCESS_TOKENAccess token required by the web application to submit and create feeds. Paste this token into the web UI when prompted (minimum 16 characters). Generate with: openssl rand -hex 32
Access token required by the web application to submit and create feeds. Paste this token into the web UI when prompted (minimum 16 characters). Generate with: openssl rand -hex 32
HTML2RSS_SECRET_KEYSecret key for encrypting session cookies and state (minimum 32 characters). Generate with: openssl rand -hex 32
Secret key for encrypting session cookies and state (minimum 32 characters). Generate with: openssl rand -hex 32
HTML2RSS_TOTAL_TIMEOUT_SECONDS50Optional; internal gem feed-build timeout in seconds; default 50
Optional; internal gem feed-build timeout in seconds; default 50
PORT4000App listen port; compose uses 4000
App listen port; compose uses 4000
RACK_ENVproductionRack environment; quickstart uses development, production examples use production
Rack environment; quickstart uses development, production examples use production
values: development/production/test
RATE_LIMIT_ENABLEDtrueOptional boolean; default true (except false in test); enables or disables client IP rate limiting
Optional boolean; default true (except false in test); enables or disables client IP rate limiting
values: true/false
RATE_LIMIT_MAX_REQUESTS60Optional integer >= 1; default 60; maximum requests allowed per IP per window
Optional integer >= 1; default 60; maximum requests allowed per IP per window
RATE_LIMIT_WINDOW_SECONDS60Optional integer >= 1; default 60; rate limiter sliding window duration in seconds
Optional integer >= 1; default 60; rate limiter sliding window duration in seconds
REQUEST_TIMEOUT_SECONDS55Optional; total web-request timeout in seconds; default 55
Optional; total web-request timeout in seconds; default 55
RETRY_AFTER_TIMEOUT_SECONDS300Optional integer >= 1; default 300; Retry-After header backoff duration returned on timeouts
Optional integer >= 1; default 300; Retry-After header backoff duration returned on timeouts
SENTRY_DSNOptional; enables Sentry errors/logs when set
Optional; enables Sentry errors/logs when set
WEB_CONCURRENCY2Optional integer >= 1; default 2 in production (1 in development); number of web worker processes
Optional integer >= 1; default 2 in production (1 in development); number of web worker processes