Obscura Headless Browser
A lightweight, stealth-capable browser engine for agent automation and web scraping without Chromium.
Loopback, private, and link-local destinations are blocked by default and require explicit opt-in; CI uses read-only permissions, avoids persisted credentials, separates PR checks from publishing, and obtains dependency policy from the trusted base revision. These provide strong least-privilege and dependency-security evidence. The security model also states that in-process execution is not OS isolation and recommends a container or VM. Deductions apply because navigation, clicks, form submissions, file writes, and proxied traffic have no per-action confirmation layer, while robots.txt compliance is off by default. Requests, cookies, proxies, outputs, and cross-session boundaries are described, but credential lifetimes, log redaction, and retention are not comprehensively documented. Closing a page resets state, yet completed requests, submissions, and writes have no rollback mechanism. Repository, license, security email, and project channels are attributable, but the publisher identity is not verified by the supplied evidence.
The README, Cargo workspace, security model, and CI matrix are broadly consistent about feature combinations, panic behavior, SSRF defaults, and supported environments. Timeouts, a V8 watchdog, a process hard deadline, and panic degradation are documented. Deductions apply because a static review cannot establish that these controls work, and several performance and compatibility claims remain project-authored. Build requirements are detailed, but V8, BoringSSL, system tooling, external release artifacts, and locally patched dependencies add availability risk. Timeout and heap-exhaustion guidance exists, though there is no comprehensive stable error taxonomy or diagnostic contract across MCP and CDP operations.
The material clearly serves AI-agent automation, scraping, CLI, MCP, Puppeteer, Playwright, CDP, parallel workloads, and several output scenarios. Installation and build variants cover Linux, macOS, Windows, Docker, AUR, and NixOS. Capability boundaries are unusually explicit about long-tail CSS, partial Web APIs, media, compositor effects, font differences, in-process isolation, and response-body cache limits. Trigger precision is deducted because snapshot-reference invalidation, navigation preconditions, selector ambiguity, duplicate-submission protection, and tool-level side-effect constraints are not fully specified.
The README has clear sections for installation, quick starts, rendering, CDP, CLI, MCP, security considerations, and integrations. Command names, feature names, and output formats remain stable across sections, while platform and dependency notes are specific. The complete Apache-2.0 license agrees with Cargo metadata, and limitations are explicitly documented. Deductions apply because there is no substantive FAQ and troubleshooting coverage is incomplete. Releases and tag-based publishing provide an update path, but no changelog or compatibility policy is supplied, and the workspace remains at version 0.1.0. Contact details and a security-response timetable exist, although the responsible legal identity and publisher provenance are not verified by the supplied files.
Outputs are directly usable by scripts and agents: HTML, text, links, Markdown, raw binary bodies, NDJSON, JSON, screenshots, PDFs, streams, and MCP resources. Quiet mode, file output, and parallel scraping strengthen usability. A standalone Rust/V8 engine with low-dependency deployment and several protocol interfaces offers plausible marginal value over Chromium-based workflows. Deductions apply because key memory, startup, page-load, compatibility, and anti-detection benefits are primarily presented as marketing claims, while the benchmark implementation is in an external repository not included here. Static evidence cannot confirm correctness, performance, proxy expense, or operational maintenance cost.
Claims are partly traceable to Cargo features, the CI build matrix, the security policy, command references, and protocol method tables. Multiple supplied files corroborate dependency auditing, supported build combinations, panic behavior, and network boundaries. Deductions apply because core implementation files, deny.toml, test bodies, the complete release pipeline, and the external benchmark repository are absent, preventing closed-loop verification of performance, resource use, compatibility, and anti-detection figures. The documentation distinguishes several limitations and future plans from current capabilities, but some marketing assertions and precise numbers omit methodology, environment, and uncertainty.
- Obscura executes arbitrary page JavaScript in process. Use containers or VMs, restricted egress, and per-user isolation for hostile inputs; the V8 watchdog is not a security sandbox.
- robots.txt compliance is disabled by default, and stealth mode includes anti-fingerprinting and tracker blocking. Operators should explicitly review site terms, authorization, and automation policies.
- MCP and CDP tools can navigate, click, fill, and submit forms, but the supplied material shows neither per-action confirmation nor reversible transactions. Do not grant unsupervised access to high-impact accounts.
- Login flows retain cookies, but comprehensive secret storage, log-redaction, cookie-persistence, and destruction policies are not documented. Sensitive sessions need isolation and cleanup by the surrounding system.
- Performance, resource-use, and anti-detection figures are not independently verifiable from the supplied files. Benchmark the intended sites, architectures, and security boundaries before adoption.
What does this agent do, and when should you use it?
Obscura is an Apache-2.0 headless browser engine written in Rust for web scraping and browser-driven agent workflows. It embeds V8 to execute real page JavaScript and exposes a Chrome DevTools Protocol server that Puppeteer and Playwright can connect to. Its independent rendering engine produces PNG screenshots, live CDP screencasts, and PDFs without launching Chromium. The distribution includes single-page `fetch`, parallel `scrape`, a CDP WebSocket service, and an MCP server available over stdio or HTTP. Teams can self-host it from platform-specific release archives, a distroless Docker image, or source; official binaries require neither Chrome nor Node.js at runtime.
The obscura fetch <URL> command requests a page, executes its scripts, and can emit HTML, readable text, links, Markdown, NDJSON asset URLs, or the original response body. It can evaluate JavaScript, wait for lifecycle events or selectors, use HTTP or SOCKS proxies, capture PNG files, and write extracted output to disk. obscura scrape <URL...> uses worker processes to visit multiple URLs concurrently and returns per-page evaluation results as JSON or text. obscura serve --port 9222 exposes CDP methods used by puppeteer.connect and chromium.connectOverCDP for navigation, DOM access, forms, cookies, request interception, input, screenshots, screencasting, and PDF output. With --stealth, a compatible build randomizes session fingerprints, masks automation signals, and prevents requests to its tracker blocklist. obscura mcp and obscura mcp --http --port 8080 expose navigation, snapshots, clicks, form input, key presses, evaluation, network logs, console messages, screenshots, and PDFs to MCP clients.
- A data-collection team can run
obscura scrapewith several workers to process URL batches and return a JavaScript-derived result for each page as JSON. - An agent developer can use the MCP server for browser navigation, structured snapshots, referenced-element clicks, form filling, keyboard events, and page evaluation.
- A team with existing Puppeteer or Playwright automation can connect over CDP and evaluate Obscura as a lighter self-hosted substitute for headless Chrome.
- A web archiving or monitoring service can create full-page PNGs, stream live page frames through CDP, or export PDFs without starting Chromium.
- A tester working with sites that deploy tracking or automation detection can use a stealth-enabled build for session fingerprint randomization and tracker blocking.
- A collector downloading images, JSON, JavaScript, CSS, or other non-HTML resources can use
--dump originalto stream the response body without passing it through the JavaScript and DOM layers.
What are this agent's strengths and limitations?
- It does not require Chromium: Obscura embeds V8 and supplies its own CSS layout, painting, screenshot, screencast, and PDF paths.
- One engine is accessible through a CLI, CDP, Puppeteer, Playwright, and MCP over either stdio or HTTP.
- Deployment choices include Linux, macOS, and Windows release archives, a roughly 57 MB compressed distroless Docker image, and source builds.
- The stealth variant provides per-session GPU, screen, canvas, audio, and battery fingerprint randomization and blocks 3,520 tracker domains.
- It supports binary-safe original response output and chunked downloads through
Fetch.takeResponseBodyAsStream,IO.read, andIO.close.
- The independent renderer is still evolving; long-tail CSS, some Web APIs, media playback, compositor effects, and platform font rasterization may differ from Chromium.
- The documented CDP table covers a defined subset of domains and methods rather than claiming complete CDP parity, so complex Chrome migrations need method-by-method testing.
- A first source build takes about five minutes because V8 compiles from source, while stealth builds add BoringSSL, CMake, Clang, and LLVM/libclang requirements.
- Parallel scraping from release archives depends on
obscura-workerremaining beside the main executable, adding a packaging constraint. - Page script execution has a default 30-second budget; heavy React, Vue, or Angular applications may require coordinated changes to
OBSCURA_SCRIPT_DEADLINE_MSand client navigation timeouts. - Response bodies larger than the default 2 MiB network cache limit are not retained; large streaming downloads require raising
OBSCURA_NETWORK_BODY_BUFFER_BYTES.
How do you install or deploy this agent?
For Linux x86_64, download and test the release binary with:
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura fetch https://example.com --eval "document.title"Release archives are also documented for Linux ARM64, macOS on Apple Silicon and Intel, and Windows. Arch Linux users can run yay -S obscura-browser; NixOS users can run nix-env -iA nixpkgs.obscura. Keep the included obscura and obscura-worker binaries in the same directory when using parallel scrape. Docker deployment is docker run -d --name obscura -p 127.0.0.1:9222:9222 h4ckf0r0day/obscura. Building from source requires Rust 1.75+; use cargo build --release -p obscura-cli --bins --features render for rendering or cargo build --release -p obscura-cli --bins --features render,stealth for rendering plus stealth. The stealth build additionally needs CMake, Clang, and the libclang/LLVM development libraries. No credentials are required for the basic local invocation, although target sites and configured proxies may impose their own authentication.
How do you use this agent?
For a first text extraction, run obscura fetch https://example.com --dump text. Capture a page with obscura fetch https://example.com --screenshot page.png. A parallel extraction can be started with obscura scrape url1 url2 url3 --concurrency 25 --eval "document.querySelector('h1').textContent" --format json. For Puppeteer or Playwright, first run obscura serve --port 9222, then connect with puppeteer.connect({ browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser' }) or chromium.connectOverCDP({ endpointURL: 'ws://127.0.0.1:9222' }). Claude Desktop can launch it with {"mcpServers":{"obscura":{"command":"obscura","args":["mcp"]}}}. Network MCP clients can connect to http://127.0.0.1:8080/mcp after obscura mcp --http --port 8080. Web navigation requires network access, while screenshots, PDFs, downloads, and output files require writable filesystem locations.
How does this agent compare with similar options?
The project explicitly presents Obscura as a replacement for headless Chrome. Its README reports about 30 MB of memory, a 70 MB binary, an 85 ms page load, near-instant startup, and built-in anti-detection, compared with 200+ MB, 300+ MB, roughly 500 ms, about two seconds, and no built-in anti-detection for headless Chrome. Both are listed as compatible with Puppeteer and Playwright. Adoption should still be validated against representative sites because Obscura's independent renderer and Web API coverage can produce behavior different from Chromium.
FAQ
Do I need Chrome or Node.js?
puppeteer-core or playwright-core, which requires an appropriate JavaScript client environment.Will the hosted Obscura Cloud reduce the open-source feature set?
Will pages render exactly as they do in Chromium?
How can I handle a heavy page or a V8 out-of-memory error?
--timeout, raise the script budget through OBSCURA_SCRIPT_DEADLINE_MS, and pass a larger heap limit such as --v8-flags "--max-old-space-size=4096". CDP client navigation timeouts should be adjusted to match the server-side script budget.Does stealth mode retain rendering and capture features?
render,stealth includes the complete rendering engine, and enabling --stealth at runtime does not remove screenshots, screencasting, PDFs, CDP, or MCP.