obscura: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents and contributors working in the Obscura repo. This is the non-obvious stuff you can't infer from the code; read it before building, testing, or changing anything.

Obscura is a headless browser engine in Rust. It runs real JavaScript through V8 (deno_core), keeps a real DOM tree, owns its layout and paint pipeline, speaks the Chrome DevTools Protocol, and is a drop-in replacement for headless Chrome with Puppeteer and Playwright. Rendering and stealth are both first-class capabilities. It targets web scraping and AI-agent automation.

Build

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render

# Rendering and stealth
CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render,stealth

# No rendering, with rustls or stealth
CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features
CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features --features stealth

• The first build compiles V8 from source: ~5 minutes and a few GB of disk. Incremental builds are seconds.
• Iterating on one crate? Scope it: cargo build -p obscura-cli. A bare cargo build can re-link the whole workspace; the V8 compile is the cost, so avoid touching it when you don't need to.
• Stealth: --features render,stealth retains the complete rendering surface and adds the wreq/BoringSSL transport, fingerprint protections, and tracker blocklist. BoringSSL builds through CMake, so cmake must be installed. The rendering build uses rustls and needs neither CMake nor OpenSSL.
• If the vendored OpenSSL build hits an AVX-512 assembler error on your host, build with OPENSSL_NO_VENDOR=1.

Test

Run tests with cargo nextest, not cargo test:

cargo nextest run --release --features render -p <crate>
cargo nextest run --release --features render --no-fail-fast