Obscura: Lightweight Headless Browser for AI Agents
/obscura
Obscura headless browser is a legitimate alternative for teams running browser automation at scale, offering a Rust-based engine with lower resource usage, faster startup, and a built-in anti-detection layer. CDP compatibility ensures most Puppeteer and Playwright scripts port over. It addresses common issues like memory overhead, page-load speed, and bot detection.
What is Obscura?
Obscura is a self-contained headless browser written in Rust that runs JavaScript via V8 and speaks the Chrome DevTools Protocol. It screenshots, scrapes, and serves a CDP WebSocket endpoint โ either from a pre-built binary you download or a Docker container โ without installing Chromium or Node.js. The project positions itself for web scraping and AI agent automation specifically, with a stealth build that randomizes browser fingerprints and blocks known trackers at the network layer.
Core Features for Automation and Scraping
- โCDP server compatible with Puppeteer and Playwright without Chromium installed
- โNative rendering engine: CSS layout, screenshots, full-page screenshots, raster PDF export โ no Chromium process
- โStealth mode: per-session fingerprint randomization across canvas, audio, GPU, and screen; blocks 3,520 tracker domains
- โMCP server for AI agents: exposes structured tools (navigate, snapshot, click, fill, screenshot, PDF) over stdio or HTTP
- โV8 JavaScript execution with adjustable script deadline (`OBSCURA_SCRIPT_DEADLINE_MS`) for heavy SPAs
- โParallel scraping with configurable concurrency, inherited proxy, and JSON/text output
- โSOCKS5 and HTTP proxy support per-command and globally
- โDocker image on distroless/cc: ~57 MB compressed, no shell, no package manager
Getting Started with Obscura
Pre-built binaries cover Linux x86_64, Linux ARM64, macOS (Apple Silicon and Intel), and Windows โ download the appropriate archive from the Releases page and extract it. Four archive variants exist: plain rendering, rendering-plus-stealth, no-render, and no-render-plus-stealth โ pick the one that matches whether you need screenshots/PDFs and whether you want anti-detection enabled. Arch Linux users can install from AUR with `yay -S obscura-browser`, and NixOS users with `nix-env -iA nixpkgs.obscura`. Docker is one line: `docker run -d --name obscura -p 127.0.0.1:9222:9222 h4ckf0r0day/obscura`. Building from source requires Rust 1.75+; the stealth+rendering build also pulls in CMake, Clang, and libclang/LLVM development libraries, and takes around five minutes on a first build due to V8 compilation from source.
Running Obscura from the Command Line
The two main subcommands are `obscura fetch` and `obscura serve`. Use `fetch` for one-shot page operations: `obscura fetch https://example.com --eval "document.title"` runs JS and prints the result, `--dump html` dumps rendered DOM, `--dump text` gives plain text, `--dump links` extracts all anchor hrefs, and `--screenshot page.png` captures a PNG. The `--wait-until networkidle0` flag waits for dynamic content to settle. For Puppeteer or Playwright scripts, start the server first with `obscura serve --port 9222` (add `--stealth` for anti-detection), then connect via WebSocket at `ws://127.0.0.1:9222/devtools/browser`. Parallel scraping across multiple URLs uses `obscura scrape url1 url2 url3 --concurrency 25 --format json`. The MCP server runs with `obscura mcp` for stdio clients like Claude Desktop, or `obscura mcp --http --port 8080` for HTTP-based agents.
Integrating with Puppeteer and Playwright
- โขRunning Puppeteer or Playwright scripts against a CDP endpoint (`obscura serve --port 9222`) instead of spawning headless Chrome โ most existing scripts connect with a one-line change to the WebSocket URL
- โขAI agent pipelines that need structured browser control: the MCP server exposes tools like `browser_navigate`, `browser_snapshot`, and `browser_click` that models can call without writing raw CDP JSON-RPC
- โขBulk scraping with `obscura scrape url1 url2 ... --concurrency 25` โ parallel workers inherit global proxy settings, output JSON or plain text, and suppress progress for scripting
- โขCapturing screenshots or PDFs of pages that would otherwise detect or block headless Chrome โ enabled by default in stealth mode
- โขFetching pages through SOCKS5 proxies with `obscura --proxy socks5://... fetch ...` for geo-targeted or IP-rotated requests
- โขScraping JS-heavy SPAs where you need to wait for `networkidle0` or a specific CSS selector to appear before evaluating or dumping content
Strengths
- โDelivers exceptional performance and resource efficiency, using only 30 MB of memory and a 70 MB binary size, with page load times averaging 85 ms and instant startup, significantly faster than typical headless Chrome setups.
- โIncludes built-in stealth and anti-detection features, offering per-session fingerprint randomization, realistic user agent data, native function masking, and blocking over 3,520 tracker domains to avoid detection during web scraping.
- โFeatures a native rendering engine built in Rust, eliminating the need for a Chromium dependency while still supporting full page rendering, screenshots, screencasting, and PDF export.
- โOffers broad compatibility with existing automation tools by implementing the Chrome DevTools Protocol for use with Puppeteer and Playwright, and provides an MCP server for direct integration with AI agents.
- โMaintains a fully featured open-source model under the Apache-2.0 license, with a commitment to no feature gating, ensuring all capabilities remain accessible to the community.
Current Rendering Capabilities and Considerations
- โณAs an independent engine, its rendering of long-tail CSS properties and values may differ from Chromium's behavior.
- โณSupport for certain Web APIs might vary or be incomplete compared to a full Chromium environment.
- โณMedia playback and compositor effects may not render identically to how they appear in Chromium.
- โณPlatform font rasterization can produce different visual results than those seen in Chromium-based browsers.
Other Headless Browser Options
Frequently Asked Questions
Yes. Obscura is released under the Apache 2.0 license, and the project states the open-source engine will always stay that way with no feature gating.
Obscura exposes a CDP WebSocket server that Puppeteer-core and Playwright-core drive exactly like headless Chrome โ connect to ws://127.0.0.1:9222/devtools/browser and use your existing scripts.
Obscura Cloud is a hosted, managed service the team is building: infrastructure, residential proxies, and dedicated support for users who prefer not to operate the engine themselves. The open-source build remains fully featured and Apache-2.0 licensed.
Stealth mode randomizes per-session fingerprints for canvas, audio, GPU, screen, and battery; sets navigator.webdriver to undefined; and blocks 3,520 known tracker domains at the network layer. Enable it at runtime with the --stealth flag when serving or fetching.
Rust 1.75 or newer is required for all builds. The rendering-plus-stealth build additionally needs CMake, Clang, and the libclang/LLVM development libraries. Expect roughly five minutes on a first build since V8 compiles from source.
Yes. Obscura runs real JavaScript via V8 and defaults to a 30-second script execution budget per page, which you can raise via OBSCURA_SCRIPT_DEADLINE_MS. Use --wait-until networkidle0 or a --selector to wait for SPA content before evaluating.
Who should try it โ and who should skip
Pick up Obscura if you are running high-volume scraping or AI agent tasks and Chrome's memory footprint or cold-start latency is a bottleneck. The stealth mode is worth it once you are actually hitting sites that fingerprint headless browsers and you want anti-detection baked into the browser process rather than layered on top. Skip it if you need rendering that exactly matches what users see in Chrome โ the independent engine still has gaps the README names explicitly โ or if your team is already invested in Playwright and the resource trade-offs are not yet a problem.
Related repositories
Still deciding about obscura?
One click hands the question to an AI along with this page โ see what it says about obscura.