🌐 OxiBrowser

The headless browser built in pure Rust for AI agents.

Not a Chromium fork. Not a C++ wrapper. A browser engine written from scratch in Rust, designed from day one for automation, web scraping, and AI-driven workflows.

Report Bug · Request Feature · Read the Docs · Discord

You're building AI agents that need to browse the web. You don't need a full browser with GPU rendering, audio output, and extension support. You need something fast, small, and programmable.

OxiBrowser is built for exactly that use case:

• 🤖 AI-Agent First — CLI designed for agents: --json output, describe for schema, skill for prompts, session for multi-step
• ⚡ Blazing Fast — Cold starts in ~50ms, no Chromium overhead, no Node.js required
• 🦀 Rust-First — boa_engine (JS, no V8), html5ever (HTML) are pure Rust. TLS uses btls (BoringSSL C binding) for stealth fingerprint emulation. Single static binary.
• 🔌 CDP Compatible — Puppeteer, Playwright, and any Chrome DevTools Protocol client works out of the box
• 🛡️ Secure by Default — SSRF protection with CIDR blocking, robots.txt respect, no sandbox escape surface
• 📦 Tiny Footprint — 24 MB binary, ~8 MB base memory. Run 100 instances without breaking a sweat

This release closes most of the gap between "HTML fetcher" and "real headless browser" — events now behave like a browser, innerHTML works for SPA-style DOM injection, and fetch returns a spec-compliant Response with arrayBuffer().

Events & DOM

• Event constructors honor the init dict — new MouseEvent('click', { clientX, clientY, ctrlKey, ... }) now actually carries those fields. Covers MouseEvent, KeyboardEvent, FocusEvent, Event, and a new DragEvent.
• dispatchEvent sets event.target / event.currentTarget and returns !defaultPrevented. preventDefault / stopPropagation / stopImmediatePropagation work on every event.
• Event bubbling walks the parent chain. Listeners are stored in a thread-local registry keyed by nodeId, so they survive across element-object re-queries (the bug that made parent.addEventListener invisible to child.dispatchEvent).
• requestAnimationFrame / cancelAnimationFrame now schedule properly with a 16 ms deadline and pass a DOMHighResTimeStamp to the callback.
• innerText getter and standalone performance global (window.performance === performance).

HTML & innerHTML

• innerHTML setter parses the fragment via html5ever and inserts child nodes into the snapshot. outerHTML getter serializes the node back. A new dom_serializer module handles the round-trip with proper void-element / attribute-escape handling (12 unit tests).

Network

• Response.text() / json() / arrayBuffer() all return spec-shaped Promises that resolve to the actual response body. fetch options headers (content-type, accept, authorization, user-agent, cookie) are now forwarded.
• SSRF filter is now scheme-aware: only http/https go through DNS/host checks. about:blank is supported (Puppeteer/Playwright's default target URL now works).

CDP

• Input.dispatchMouseEvent emits a real sequence: mousePressed → mousedown; mouseReleased → mouseup + click; mouseMoved → mousemove. Input.dispatchDragEvent is wired to a DragEvent on the element at the point.

cargo install oxibrowser

$ oxibrowser fetch https://example.com

Example Domain

# Example Domain

This domain is for use in documentation examples...
[Learn more](https://iana.org/domains/example)

$ oxibrowser fetch https://example.com --json
{"ok":true,"data":{"url":"https://example.com/","title":"Example Domain","status":200,"markdown":"..."},"meta":{"elapsed_ms":152}}

$ oxibrowser extract https://example.com --links --json
{"ok":true,"data":{"links":["https://iana.org/domains/example"],"title":"Example Domain"}}

$ oxibrowser session
new
{"ok":true,"data":{"tab_id":"t1"}}
goto t1 https://example.com
{"ok":true,"data":{"status":200,"title":"Example Domain"}}
eval t1 document.title
{"ok":true,"data":{"value":"Example Domain"}}
close t1
{"ok":true,"data":{"closed":"t1"}}
exit
{"ok":true,"data":{"exit":true}}

oxibrowser serve --port 9222

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://127.0.0.1:9222',
});

const page = await browser.newPage();
await page.goto('https://news.ycombinator.com');
console.log(await page.title());
await browser.close();

oxibrowser <COMMAND>

COMMANDS:
  fetch      Fetch a URL and return content (markdown default)
  extract    Extract structured data (links, text, elements)
  run        Run a YAML automation script
  session    Interactive stdin/stdout JSON REPL (22 commands)
  serve      Start CDP WebSocket server
  search     Web / GitHub / GitHub-issues search (no browser needed)
  describe   Print CLI schema as JSON (for agents)
  skill      Print agent skill guide
  version    Print version information

# Human-readable (markdown, default)
oxibrowser fetch https://example.com

# Agent mode
oxibrowser fetch https://example.com --json

# Click then read
oxibrowser fetch https://example.com --click button --wait .result --json

# Quick page summary
oxibrowser fetch https://example.com --summary --json

# Run JS
oxibrowser fetch https://example.com --eval "document.title" --json

# Limit response size
oxibrowser fetch https://example.com --max-bytes 8000 --json

# Select specific fields
oxibrowser fetch https://example.com --fields url,title,status --json

# Get all links
oxibrowser extract https://example.com --links --json

# Extract elements by CSS selector
oxibrowser extract https://example.com --selector "a" --all --attrs text,href --json

# Title + full text
oxibrowser extract https://example.com --title --text --json

oxibrowser session  # Start REPL

# 22 commands:
new, goto, back, forward, reload, click, fill, press, type,
select, check, uncheck, scroll, eval, extract, content,
screenshot, wait, close, close --all, list, help, exit

# Compact (~200 tokens)
oxibrowser describe --compact

# Full command details
oxibrowser describe fetch
oxibrowser describe session

# Web search (DuckDuckGo)
oxibrowser search "rust async" --engine ddg --max-results 5 --json

# GitHub search
oxibrowser search "memory pool" --source github --json

# GitHub issues for a specific repo
oxibrowser search "panic on shutdown" --source github-issues --repo a7garden/oxibrowser --json

name: example
steps:
  - step_type: goto
    data:
      goto: https://example.com
  - step_type: content
    data:
      format: markdown

oxibrowser run script.yaml

All --json responses follow the same schema:

{
  "ok": true,
  "data": { ... },
  "meta": { "elapsed_ms": 152 }
}

On error:

{
  "ok": false,
  "error": "URL scheme must be http or https",
  "error_code": "INVALID_URL"
}

Exit codes: 0=success, 1=runtime, 2=input validation, 3=timeout, 4=network

┌──────────────────────────────────────────────────────┐
│            Puppeteer / Playwright / Rust CDP          │
└────────────────────────┬─────────────────────────────┘
                         │ CDP WebSocket
                         ▼
┌──────────────────────────────────────────────────────┐
│                 CDP Server (10 domains)               │
│  Browser · DOM · Fetch · Input · Network             │
│  OXI · Page · Runtime · Target                       │
├──────────────────────────────────────────────────────┤
│          Browser → Session → Page → Frame            │
├──────────┬──────────┬──────────────┬─────────────────┤
│  WebAPI  │  Network │  JS Runtime  │  CSS Rendering  │
│  DOM     │  HTTP    │  boa_engine  │  PNG screenshot │
│  Tree    │  Cookies │  ES2024+     │  ASCII/Unicode  │
│  Storage │  SSRF    │  persistent  │  text→image     │
├──────────┴──────────┴──────────────┴─────────────────┤
│   html5ever · encoding_rs · reqwest · image · boa    │
└──────────────────────────────────────────────────────┘

Designed for AI agent workflows — no daemon, no socket, single binary:

Powered by boa_engine — pure Rust, no V8 dependency:

10 domain handlers — Puppeteer and Playwright compatible:

import websockets, json, asyncio

async def ai_scrape():
    ws = await websockets.connect('ws://localhost:9222/ws')
    
    await ws.send(json.dumps({
        "id": 1, "method": "Page.navigate",
        "params": {"url": "https://news.ycombinator.com"}
    }))
    await asyncio.sleep(2)
    
    # Clean markdown — perfect for LLM ingestion
    await ws.send(json.dumps({"id": 2, "method": "OXI.getMarkdown"}))
    resp = json.loads(await ws.recv())
    print(resp['result']['markdown'])

• ASCII/Unicode text output — Render DOM to readable text with proper indentation
• Markdown conversion — Full HTML→Markdown with heading, link, and list support
• PNG screenshots — Built-in 8×16 bitmap font, renders text content as images
• No external dependencies — Font data embedded in binary

# Run all tests
cargo test --workspace

# CLI integration tests (fast, no network)
cargo test -p oxibrowser --test cli

# E2E CDP tests
cargo test -p oxibrowser-cdp

# Integration tests (real websites, requires internet)
cargo test --workspace -- --ignored

use oxibrowser_core::Browser;
use oxibrowser_core::config::BrowserConfig;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::new(BrowserConfig::default()).await?;
    let session = browser.new_session().await?;
    
    session.navigate("https://example.com").await?;
    
    let title = session.evaluate("document.title").await?;
    println!("Title: {:?}", title);
    
    Ok(())
)
}

[dependencies]
oxibrowser-core = "0.11"
# Or the CDP server:
oxibrowser-cdp = "0.11"

const client = await page.target().createCDPSession();

await client.send('Fetch.enable', {
    patterns: [{ urlPattern: '*ads*' }]
});

client.on('Fetch.requestPaused', async ({ requestId }) => {
    await client.send('Fetch.failRequest', {
        requestId,
        reason: 'BlockedByClient'
    });
});

See CONTRIBUTING.md for full guidelines.

git clone https://github.com/a7garden/oxibrowser.git
cd oxibrowser
cargo build
cargo test --workspace
cargo clippy --workspace -- -D warnings

OxiBrowser is licensed under the MIT License.

• boa_engine — Pure Rust JavaScript engine (ES2024+)
• html5ever — HTML parser from the Servo project
• reqwest — Ergonomic HTTP client for Rust
• tokio — Async runtime powering the entire networking stack