obscura-node

obscura-node

Node.js wrapper for Obscura — the Rust-powered headless browser built for AI agents and web scraping. Drop-in replacement for headless Chrome with Puppeteer & Playwright. Includes a one-shot ObscuraFetch API for lightning-fast page fetching.

---

What is Obscura?

Obscura is an open-source headless browser engine written from scratch in Rust — not a fork or fork of Chromium. It runs real JavaScript via V8 (deno_core), builds a live DOM from parsed HTML, and exposes the Chrome DevTools Protocol (CDP) over WebSocket. This means it works as a drop-in replacement for headless Chrome with Puppeteer and Playwright — but at a fraction of the resource cost.

obscura-node gives you two ways to use Obscura:

• loadObscura() — spawns obscura serve, returns a CDP WebSocket endpoint for use with Puppeteer, Playwright, or any CDP client.
• ObscuraFetch() — one-shot obscura fetch call. Fetches a URL, renders the page (JS, DOM), and returns the output as a string. No server setup, no WebSocket, no cleanup.

obscura-node is a Node.js wrapper around Obscura — the incredible Rust headless browser built by @h4ckf0r0day. All credit for the browser engine, stealth, benchmarks, and CDP implementation goes to the original author. This package just makes it easy to use from Node.js.

---

Why Obscura over Headless Chrome?

Metric	Obscura	Headless Chrome	Advantage
Memory per instance	~30 MB	200+ MB	6-10x less
Binary size	~70 MB	300+ MB	4x smaller
Page load (static)	~51 ms	~500 ms	10x faster
Page load (dynamic)	~85 ms	~800 ms	9x faster
Startup time	Instant (~50 ms)	~2 seconds	40x faster
Anti-detection	Built-in (--stealth)	None
Tracker blocking	3,520 domains	None
SSRF protection	Built-in	None
DOM → Markdown	Native CDP method	None
Puppeteer / Playwright	Full CDP		Identical
Single binary	Yes	Needs Chrome

Head-to-head benchmark (from obscura-benchmark)

Framework pages (cold start):

Page	Obscura	Headless Chrome	Advantage
React	88 ms, 30 MB	1,097 ms, 185 MB	12x faster, 6x less memory
Preact	59 ms, 29 MB	1,032 ms, 186 MB	18x faster, 6x less memory
Vue	97 ms, 32 MB	1,144 ms, 184 MB	12x faster, 6x less memory

Concurrent throughput (8 workers):

Engine	Throughput	Peak memory
Obscura	21 pg/s	132 MB
Headless Chrome	2.8 pg/s	7.1 GB

Real-world corpus (24 public sites):

Metric	Obscura	Headless Chrome
Render success	91.7%	91.7%
Median latency	2.0 s	1.5 s
Median peak RSS	35.6 MB	191.8 MB

Source: obscura-benchmark — conformance, obstacle course, vs-Chrome, and real-world corpus benchmarks.

Key takeaway: Independent benchmarks confirm Obscura uses ~30 MB memory (vs Chrome's 200-300 MB), has dramatically lower variance (σ 16ms vs Chrome's 76ms on HN), and delivers identical rendering results on real pages.

---

Features

• Two APIs — loadObscura() for CDP-based multi-page sessions (Puppeteer/Playwright), ObscuraFetch() for one-shot page fetching
• One-shot ObscuraFetch — fetch any URL and get rendered output (HTML, text, markdown, links, assets) in a single call. Significantly faster than spinning up a full CDP server
• Zero dependencies — single Rust binary, no Chrome/Node.js runtime required
• Automatic download — installs the right binary for your platform (Linux x64, macOS ARM/x64, Windows x64)
• CDP WebSocket endpoint — use with Puppeteer, Playwright, or any CDP client
• Stealth mode — pass stealth: true for anti-fingerprinting + tracker blocking
• Flexible port/host — auto-find free port or specify one
• Graceful shutdown — proper SIGTERM → SIGKILL cleanup
• Custom args — pass extra flags to the Obscura binary
• Configurable timeout — control how long to wait for startup

---

Installation

npm install obscura-node

The Obscura binary downloads automatically on the first loadObscura() or ObscuraFetch() call if not present.

---

Quick Start

One-shot fetch (v1.1.0+)

import { ObscuraFetch } from "obscura-node";

const html = await ObscuraFetch("https://example.com");
console.log(html);

// Get text content instead
const text = await ObscuraFetch("https://example.com", { dump: "text" });
console.log(text);

CDP server (Puppeteer / Playwright)

import loadObscura from "obscura-node";

const browser = await loadObscura();

console.log(browser.endpoint);    // http://127.0.0.1:58291
console.log(browser.wsEndpoint);  // ws://127.0.0.1:58291/...

// Use with Puppeteer:
import puppeteer from "puppeteer";
const browser = await puppeteer.connect({
  browserWSEndpoint: obscura.wsEndpoint,
});
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

// Cleanup
await obscura.close();

---

API Reference

ObscuraFetch(url, options?) — v1.1.0+

One-shot fetch. Spawns obscura fetch <url> --dump <format>, renders the page with full V8 JavaScript, and returns the output. No persistent server, no WebSocket, no cleanup needed.

import { ObscuraFetch } from "obscura-node";

const result = await ObscuraFetch("https://example.com", {
  dump: "markdown",
  stealth: true,
  timeout: 15,
});

Options (FetchOptions)

Property	Type	Default	CLI flag	Description
dump	"html" | "text" | "markdown" | "links" | "assets" | "original"	"html"	--dump	Output format
selector	string	—	--selector	CSS selector to extract specific elements
wait	number	5	--wait	Seconds to wait before capturing
timeout	number	30	--timeout	Total timeout in seconds
waitUntil	"domcontentloaded" | "load" | "networkidle2" | "networkidle0"	"load"	--wait-until	When to consider navigation complete
userAgent	string	—	--user-agent	Custom user agent
proxy	string	—	--proxy	HTTP or SOCKS5 proxy URL
stealth	boolean	false	--stealth	Enable anti-fingerprinting + tracker blocking
eval	string	—	--eval	JavaScript expression to evaluate in the page
output	string	—	--output	Write output to a file instead of stdout
quiet	boolean	false	--quiet	Suppress info logs
verbose	boolean	false	--verbose	Enable debug logging

Dump formats

Format	Description
html	Rendered HTML after JavaScript execution
text	Plain text with navigation/header/footer stripped
markdown	Clean Markdown via native DOM-to-Markdown conversion (LP.getMarkdown)
links	List of all links on the page
assets	Inventory of page sub-resources
original	Raw unmodified source

---

loadObscura(options?)

Starts a persistent CDP server (obscura serve) for multi-page sessions with Puppeteer, Playwright, or any CDP-compatible client.

Options

Property	Type	Default	Description
host	string	"127.0.0.1"	Bind address for the CDP server
port	number	Auto (free port)	CDP WebSocket port
stealth	boolean	false	Enable anti-detection + tracker blocking
startupTimeoutMs	number	10000	Timeout for binary startup
extraArgs	string[]	[]	Additional CLI flags passed to obscura serve

Returns

Property	Type	Description
endpoint	string	HTTP URL (e.g. http://127.0.0.1:9222)
wsEndpoint	string	WebSocket CDP URL (e.g. ws://127.0.0.1:9222/...)
close	() => Promise<void>	Kills the Obscura process

---

Advanced Usage

With Puppeteer

import loadObscura from "obscura-node";
import puppeteer from "puppeteer";

const obscura = await loadObscura({ stealth: true });
const browser = await puppeteer.connect({ browserWSEndpoint: obscura.wsEndpoint });
const page = await browser.newPage();

await page.goto("https://example.com");
const title = await page.title();
console.log(title);

await browser.close();
await obscura.close();

With Playwright

import loadObscura from "obscura-node";
import { chromium } from "playwright";

const obscura = await loadObscura();
const browser = await chromium.connectOverCDP(obscura.endpoint);
const page = await browser.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
await obscura.close();

Stealth mode

const browser = await loadObscura({
  stealth: true,  // anti-fingerprinting + blocks 3,520 tracker domains
});

Equivalent to obscura serve --stealth. Enables per-session fingerprint randomization (GPU, screen, canvas, audio, battery), navigator.webdriver = undefined, native function masking, and TLS ClientHello randomization.

Custom host and port

const browser = await loadObscura({
  host: "0.0.0.0",  // listen on all interfaces
  port: 9222,        // fixed port
});

Extra CLI arguments

const browser = await loadObscura({
  stealth: true,
  extraArgs: [
    "--proxy", "socks5://127.0.0.1:9050",
    "--user-agent", "Mozilla/5.0 ...",
    "--workers", "4",
  ],
});

See the Obscura CLI reference for all available flags.

---

Environment Variables

Variable	Default	Description
OBSCURA_RELEASE_TAG	v0.1.8	GitHub release tag for the Obscura binary
OBSCURA_DOWNLOAD_BASE_URL	https://github.com/h4ckf0r0day/obscura/releases/download	Override download URL
NODE_OBSCURA_SKIP_DOWNLOAD	—	Set to "1" to skip binary download

---

Platform Support

OS	Architecture	Supported
Linux	x64
macOS	ARM64 (Apple Silicon)
macOS	x64 (Intel)
Windows	x64

---

Use Cases

• AI agents — give agents a lightweight, stealth-capable browser for web research and interaction
• Web scraping — extract data at scale with 10x less memory than headless Chrome
• Automated testing — run Puppeteer/Playwright tests with faster startup and lower resource usage
• MCP servers — Obscura ships a built-in MCP server for AI agent tools (obscura mcp)
• CI/CD pipelines — single binary, no Chrome install needed, Docker-friendly (distroless image ~57 MB)

---

How it works

obscura-node (npm package)
       │
       ├── src/utils/install.ts  →  Downloads Obscura binary from GitHub releases
       │                            Extracts to src/binaries/<platform>/obscura
       │
       ├── ObscuraFetch(url, opts)
       │     └──  spawns `obscura fetch <url> --dump <format> ...`
       │          Captures stdout  →  returns rendered content as string
       │
       └── loadObscura(opts)
             └──  spawns `obscura serve --port <port>`
                  Polls CDP /json/version until ready
                  Returns { endpoint, wsEndpoint, close }

---

Related

• Obscura (Rust engine) — the core headless browser
• obscura-benchmark — official benchmarks
• Puppeteer — CDP browser automation library
• Playwright — cross-browser automation framework

---

License

ISC

---

Credits

Obscura was created by @h4ckf0r0day. This Node.js wrapper is maintained separately but relies entirely on the original Obscura binary. If you find this useful, please also star the original repo.