saifyxpro / HeadlessX

What This Repo Claims

"The undetected self-hosted browser automation platform. Powered by Camoufox (Firefox) for 0% detection rates."

Self-hosted alternative to Browserless. Run it locally, hit it via REST API, extract HTML or Markdown from any page without being detected as a bot. That's the pitch.

What I Tested

Environment: macOS Apple Silicon, balajiloganathan user, Docker 28.3.2, Node.js v20.19.6, headlessx CLI v0.1.24

Task: Start the stack and extract content from news.ycombinator.com via the REST API.

Install

npm install -g @headlessx-cli/core
headlessx init
# Choose: self-host
# Start with Docker: Yes

Three commands. CLI bootstraps the full Docker stack automatically — api, worker, postgres, redis, web dashboard, html-to-md service, yt-engine. All services came up cleanly. Mode: self-host

API: http://localhost:38473

Dashboard: http://localhost:34872

Started: yes

The Test

# HTML extraction
curl -X POST http://localhost:38473/api/operators/website/scrape/html \
  -H "x-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

# Markdown extraction  
curl -X POST http://localhost:38473/api/operators/website/scrape/content \
  -H "x-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

Both returned clean results. HTML extraction returned the full rendered page in 25 seconds. Markdown extraction returned structured content with titles, points, and comment counts correctly parsed.

The Gotcha

Two things that will trip you up:

1. API key location. The CLI doesn't tell you where the key is. It lives at ~/.headlessx/repo/infra/docker/.env under DASHBOARD_INTERNAL_API_KEY.

2. Endpoint paths changed in v2. The health endpoint advertises /api/operators/website/* but the actual working routes are:

• /api/operators/website/scrape/html — fast HTML, no JS
• /api/operators/website/scrape/html-js — HTML with JS rendering
• /api/operators/website/scrape/content — clean Markdown
• /api/operators/website/scrape/screenshot — full page screenshot

Verdict: SOLID

Stack starts cleanly, extraction works, Camoufox-powered Firefox handles real pages without bot detection issues. The CLI makes Docker setup genuinely easy. Fits the job seeker stack as the stealth scraping layer for reading job postings from sites that block standard scrapers.