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 22+
- pnpm 9+ (
npm install -g pnpm)- Mise (Task Runner)
- Docker (Optional, for containerized deployment)
- 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 .envEdit .env with your database connection:
# REQUIRED: Your PostgreSQL connection string
DATABASE_URL="postgresql://user:password@host:5432/database"
# Optional: Server configuration
PORT=8000
NODE_ENV=developmentUsing Mise (Recommended):
# Install dependencies, setup database, and download Camoufox
mise run setupOr manually:
pnpm install
pnpm --filter api db:push
pnpm --filter api exec camoufox-js fetchUsing Mise (Recommended):
# Start both frontend and backend concurrently
mise run devOr manually:
pnpm devHeadlessX can be easily deployed using Docker Compose. See the Docker Setup Guide for detailed instructions.
# Start the application in detached mode
docker compose -f infra/docker/docker-compose.yml up -d| Service | URL | Notes |
|---|---|---|
| 🖥️ Dashboard | http://localhost:3000 | Frontend UI |
| 🔗 Backend API | http://localhost:8000 | REST API |
You can customize ports via environment variables:
# Backend (from root)
PORT=8000 pnpm --filter api dev
# Frontend
PORT=3000 pnpm --filter web 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:8000/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 |
8000 |
Backend API port |
DATABASE_URL |
- | PostgreSQL connection (Supabase or self-hosted) |
NEXT_PUBLIC_API_URL |
http://localhost:8000 |
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 apps/api
# 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 apps/web
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.
