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
/api/operators/website/html returns 404. The README hasn't caught up with v2.
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.
This review follows RepoVerifier Standard v1.0. [Read the standard →](https://repoverifier.dev/about)