h4ckf0r0day/obscura repository overview

Obscura

Official Docker image for Obscura⁠ Lightweight headless browser built for AI agents and web scraping.

Obscura runs real JavaScript via V8, supports the Chrome DevTools Protocol, and acts as a drop-in replacement for headless Chrome with Puppeteer and Playwright. Compatible with:

• Puppeteer / Playwright (via CDP connect_over_cdp)
• chromiumoxide / headless_chrome (Rust CDP clients)
• Any MCP client (Claude Code, Cursor, Aider, etc.)

Why Obscura:

• Tiny — ~70 MB binary, ~30 MB RAM at runtime
• Fast — instant cold start, no Chrome bloat
• Stealthy — built-in tracker blocking, navigator.webdriver masked
• Lightweight container — built on distroless/cc (no shell, no package manager)

⁠Usage

⁠CDP server (default)

docker run -d --name obscura -p 127.0.0.1:9222:9222 h4ckf0r0day/obscura

Then connect with Playwright / Puppeteer at ws://127.0.0.1:9222/devtools/browser.

⁠Using docker compose

services:
  obscura:
    image: h4ckf0r0day/obscura:latest
    restart: unless-stopped
    ports:
      - '127.0.0.1:9222:9222'

⁠Fetch a single page

docker run --rm h4ckf0r0day/obscura fetch --dump html https://example.com

Other dump formats: text, markdown, links.

⁠Parallel scrape

docker run --rm h4ckf0r0day/obscura scrape \
  https://example.com https://news.ycombinator.com \
  --eval "document.title" --concurrency 10

⁠MCP server for AI agents

Stdio mode (default) — for Claude Code, Cursor, and other MCP clients:

docker run --rm -i h4ckf0r0day/obscura mcp

HTTP mode:

docker run -d --name obscura-mcp -p 127.0.0.1:3000:3000 \
  h4ckf0r0day/obscura mcp --http --host 0.0.0.0 --port 3000

Exposes 12 browser tools: browser_navigate, browser_snapshot, browser_click, browser_fill, browser_type, browser_evaluate, browser_wait_for, and more.

⁠Version

docker run --rm h4ckf0r0day/obscura --version

⁠Tags

• latest — most recent stable release
• 0.1.3, 0.1.2, ... — pinned versions

⁠Notes

• The default CMD binds to 0.0.0.0 inside the container so the port is reachable via docker run -p mapping. The native binary still defaults to 127.0.0.1 (loopback only).
• Stealth mode is not included in the Docker image — for now, use the source build⁠ with --features stealth if you need it.

⁠Links

• GitHub: https://github.com/h4ckf0r0day/obscura⁠
• Issues: https://github.com/h4ckf0r0day/obscura/issues⁠
• Releases: https://github.com/h4ckf0r0day/obscura/releases⁠