Powered by Camoufox — Firefox with C++ level fingerprint spoofing
📖 Documentation • 🚀 Quick Start • 🐛 Report Bug • ✨ Request Feature
| 🦊 Camoufox Engine | 🛡️ 0% Detection | ⚡ 3x Faster |
|---|---|---|
| Firefox with binary-level stealth patches | Passes CreepJS, Sannysoft, & all major tests | Optimized context pooling |
+ 🦊 NEW: Camoufox browser engine (replaces Chromium + stealth plugins)
+ 🛡️ NEW: 0% headless detection rate (was 67%+)
+ 🔒 NEW: Built-in WebRTC leak protection
+ 🎭 NEW: C++ level Canvas/WebGL/AudioContext fingerprint spoofing
+ ⚡ IMPROVED: Faster browser launches with persistent contexts
- 🧹 REMOVED: playwright-extra (no longer needed)
- 🧹 REMOVED: puppeteer-extra-plugin-stealth (no longer needed)| Tool | Headless Detection | Stealth Score | Engine |
|---|---|---|---|
| 🦊 HeadlessX V2.0 (Camoufox) | ✅ 0% | ✅ 0% | Firefox (C++ patched) |
| HeadlessX V1 (Playwright Extra) | ❌ 67% | Chromium (JS patches) | |
| Puppeteer Stealth | ❌ 33% | ❌ 80% | Chromium (JS patches) |
| Vanilla Playwright | ❌ 100% | ❌ 100% | Chromium |
| Vanilla Selenium | ❌ 100% | ❌ 100% | Chrome |
Lower scores = better (0% = undetectable)
 Google SERP |
🌐 Website Scraping |
|---|---|
| Extract search results with zero detection | Scrape any website with full JS rendering |
| ✅ Live | ✅ Live |
 Amazon |
 LinkedIn |
 Twitter |
 Instagram |
|---|---|---|---|
| Product & Reviews | Job Listings & Profiles | Tweets & Trends | Posts & Stories |
| Pixelscan (Human Detection) | Profile Tested with Proxy |
|---|---|
 |
 |
- 🆕 What's New in V2.0
- 📊 Detection Benchmark Comparison
- 🤖 Scrapers
- 🖥️ UI Screenshots
- 📸 Proof of Undetectability
- 📋 Table of Contents
- ⚡ Quick Start
- 🔥 Key Features
- 🌐 API Endpoints
- Configuration
- 🛠️ Manual Setup
- 🤝 Contributing
- 📝 License
- 🌟 Star History
Prerequisites:
- Node.js 18+ (v22+ recommended)
- pnpm 9+ (
npm install -g pnpm)- PostgreSQL Database — either:
- Supabase (recommended, free tier available)
- Self-hosted PostgreSQL 14+
git clone https://github.com/your-repo/HeadlessX.git
cd HeadlessX
# Copy environment template
cp .env.example backend/.envEdit backend/.env with your database connection:
# REQUIRED: Your PostgreSQL connection string
DATABASE_URL="postgresql://user:password@host:5432/database"
# Optional: Server configuration
PORT=3001
NODE_ENV=development💡 Supabase Users: Find your connection string at:
Dashboard → Settings → Database → Connection String (URI)
# Install all packages (workspace: root, backend, frontend)
pnpm install
⚠️ If you see a Prisma warning during install, that's normal!
It means you need to configureDATABASE_URLfirst, then runpnpm db:push.
| Windows | Linux / macOS |
install.bat |
chmod +x install.sh
./install.sh |
# Push Prisma schema to your database
pnpm db:push
# Or use migrations for production
pnpm db:migrate# Start both frontend and backend concurrently
pnpm devOr start individually:
| Windows | Linux / macOS |
scripts\start.bat |
./scripts/start.sh |
| Service | URL | Notes |
|---|---|---|
| 🖥️ Dashboard | http://localhost:3000 | Frontend UI |
| 🔗 Backend API | http://localhost:3001 | REST API |
You can customize ports via environment variables:
# Backend (from root)
cross-env PORT=4001 pnpm dev:backend
# Frontend (Linux/macOS)
PORT=4000 pnpm --filter headlessx-frontend dev
|
|
| Endpoint | Method | Description |
|---|---|---|
/api/website/html |
POST |
Get raw HTML (fast) |
/api/website/html-js |
POST |
Get HTML with JS rendering |
/api/website/content |
POST |
Get Markdown content |
/api/website/screenshot |
POST |
Capture full-page Screenshot |
/api/website/stream |
POST |
Real-time SSE Stream |
| Endpoint | Method | Description |
|---|---|---|
/api/google-serp/search |
POST |
Extract Google search results |
/api/google-serp/stream |
GET |
Real-time SSE Stream |
curl -X POST http://localhost:3001/api/website/html \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"url": "https://example.com", "stealth": true}'{
"success": true,
"data": {
"url": "https://example.com",
"title": "Example Domain",
"html": "<!DOCTYPE html>...",
"statusCode": 200
}
}
⚠️ Note: Most configuration (Browsers, Stealth, Proxy, Timeouts) is managed directly via the Dashboard Settings.
Only the following core variables are required in .env:
| Variable | Default | Description |
|---|---|---|
PORT |
3001 |
Backend API port |
DATABASE_URL |
- | PostgreSQL connection (Supabase or self-hosted) |
NEXT_PUBLIC_API_URL |
http://localhost:3001 |
Frontend API URL |
Configure these live at /settings:
- Headless Mode: Run browser without UI (faster execution)
- Browser Timeout: Max execution time per job (default: 60000ms)
- Max Concurrent Jobs: Concurrent scraping jobs (recommended: 3-8)
- Block WebRTC: Prevent IP leaks via WebRTC
- Camoufox GeoIP: Spoof location based on IP
- Enable Cache: Cache resources for speed
- Manage proxy configurations and rotation settings
cd backend
# 1. Configure environment
cp ../.env.example .env
# Edit .env with your DATABASE_URL
# 2. Install dependencies
pnpm install
# 3. Download Camoufox browser
npx camoufox-js fetch
# 4. Setup database
npx prisma db push
# 5. Start dev server
pnpm devcd frontend
pnpm install
pnpm devContributions are welcome! Please read our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
