Browser Module
Manages the Camoufox browser lifecycle with crash detection and automatic recovery.
BrowserService
isReady(): boolean
Returns whether the browser is initialized and responsive.
getPage(): Promise<Result<Page, BrowserError>>
Creates a new browser page with the configured timeout. Returns a Playwright Page object.
Lifecycle
onModuleInit()— launches Camoufox via thecamoufox-jslibraryonModuleDestroy()— graceful browser shutdown- Crash recovery — detects browser crashes and relaunches (max 3 retries)
What is Camoufox?
Camoufox is a stealth browser based on Firefox, designed to avoid bot detection. It patches browser fingerprinting vectors that headless Chrome/Playwright expose.
The project uses it for:
- Reddit scraping (avoids rate limiting)
- TikTok uploads (avoids CAPTCHA triggers)
Configuration
| Variable | Default | Description |
|---|---|---|
BROWSER_HEADLESS | true | Run headless (set false for login) |
BROWSER_USER_DATA_DIR | ./data/browser-state | Persistent session storage |
BROWSER_TIMEOUT_MS | 30000 | Page operation timeout |
BROWSER_HUMANIZE_DELAYS | true | Add random delays between actions |
Error Codes
| Code | Description |
|---|---|
LAUNCH_FAILED | Camoufox binary not found or failed to start |
NOT_READY | Browser not initialized yet |
PAGE_CREATION_FAILED | Could not create new page |
BROWSER_CRASHED | Browser process exited unexpectedly |