# Owl Browser — Product Overview

**The browser engine for automation at scale.**

Owl Browser is a high-performance browser engine built on a custom Chromium/CEF with C++ source-level fingerprint spoofing compiled directly into the Blink renderer. It is designed as a self-hosted replacement for Playwright and Puppeteer. The browser combines advanced antidetect capabilities (27 C++ override modules, 31 Chromium patches) with natural language interaction, enabling developers to build undetectable automation at scale. Because spoofing is implemented at the Chromium source level, spoofed values are produced by the same code paths as genuine browser properties — making them undetectable by JavaScript introspection, toString() analysis, or prototype chain checks. The browser features a built-in vision LLM for intelligent page understanding, 178+ automation tools for comprehensive control, and fingerprint virtualization that defeats modern bot detection systems. Deploy as a Docker container with a built-in React control panel, REST API, WebSocket, and MCP integration.

**Website**: https://www.owlbrowser.net | **By**: Olib AI (https://www.olib.ai)

## Key Features

- **178+ Automation Tools** - Complete browser control via REST API, WebSocket, and MCP protocol (160+ MCP tools for AI agent integration).
- **Agent Rendering (v1.2.0)** - Banish slow, expensive screenshots. Render pages in OwlMark: compact, structured page views built for LLMs that allow even non-vision models to browse and navigate the web with 100% precision while reducing context window and token usage by up to 10x. Re-observe unchanged pages with zero-copy delta mode.
- **Natural Language Selectors** - Click, type, and interact using descriptions like "search button" or "email input" instead of brittle CSS selectors.
- **Built-in Vision LLM** - On-device llama.cpp server with Qwen3-VL-2B model for page understanding, CAPTCHA solving, and intelligent automation.
- **Third-Party LLM Support** - Connect to OpenAI, Claude, or any OpenAI-compatible API.
- **Undetectable Stealth** - C++ source-level fingerprint spoofing compiled into a custom Chromium build (27 override modules, 31 patches), no JavaScript injection — spoofed values come from the same Blink code paths as real values, passing fingerprint.com and similar services.
- **Docker-First Deployment** - Production-ready container with nginx, React control panel, TOR integration, and s6-overlay process supervision.
- **Multi-Context Isolation** - Run up to 256 isolated browser sessions with unique fingerprints from a single instance.
- **64-Socket Parallel IPC** - Concurrent command execution via a pool of Unix domain socket connections.
- **Content Extraction** - Readability, HTML-to-Markdown, JSON extraction, site-specific templates, and full-site crawling.
- **Cross-Platform** - Native builds for macOS (arm64/x64), Linux (x64), and Windows (x64).
- **SDKs** - Official Node.js and Python SDKs with async-first design and dynamic OpenAPI method generation.
- **Owl Sidecar** - Free companion app that turns any device you own into a private residential exit for Owl Browser. Peer-to-peer tunnel; Olib servers are never in the data path. Download: https://github.com/Olib-AI/owl-sidecar

## Architecture Overview

Owl Browser follows a modular architecture with four layers: client applications, HTTP middleware, browser core, and container infrastructure.

```
+===================================================================+
|                     Docker Container                               |
|                                                                    |
|  +-------------------------------------------------------------+  |
|  |  nginx (port 80/443)         s6-overlay supervised           |  |
|  |  - React Control Panel (/)                                   |  |
|  |  - API proxy (/execute/*, /ws, /tools, /health)              |  |
|  |  - TLS termination, gzip, security headers                   |  |
|  +-------------------------------+-----------------------------+   |
|                                  |                                 |
|  +-------------------------------v-----------------------------+   |
|  |  HTTP Server (port 8080)      C99, poll-based               |   |
|  |  +-------------------------------------------------------+  |  |
|  |  | REST API | WebSocket | Auth | Rate Limit | CORS | Help |  |  |
|  |  +-------------------------------------------------------+  |  |
|  |  | Async IPC Layer (64-socket pool, request ID matching)  |  |  |
|  |  +-------------------------------------------------------+  |  |
|  +-------------------------------+-----------------------------+   |
|                                  |                                 |
|  +-------------------------------v-----------------------------+   |
|  |  Owl Browser Core            CEF (Chromium)                 |   |
|  |  +----------+  +----------+  +----------+  +----------+    |   |
|  |  | Context  |  | Context  |  | Context  |  | Context  |    |   |
|  |  |    1     |  |    2     |  |    3     |  |   ...    |    |   |
|  |  +----------+  +----------+  +----------+  +----------+    |   |
|  |                                                             |   |
|  |  +--------------+  +--------------+  +------------------+   |   |
|  |  | Stealth      |  | AI Layer     |  | Media Layer      |   |   |
|  |  | - VM Profiles|  | - llama.cpp  |  | - Recording      |   |   |
|  |  | - GPU Virt.  |  | - Vision LLM |  | - Live Streaming |   |   |
|  |  | - Spoof Mgr  |  | - NLA Engine |  | - Screenshots    |   |   |
|  |  +--------------+  +--------------+  +------------------+   |   |
|  +-------------------------------------------------------------+   |
|                                                                    |
|  +---------------------+                                          |
|  |  TOR (SOCKS: 9050)  |  s6-overlay supervised                  |
|  +---------------------+                                          |
+===================================================================+
                    |
    +---------------+----------------+------------------+
    |               |                |                  |
+---v---+     +-----v-----+   +-----v------+    +------v-----+
|Node.js|     |  Python   |   |    MCP     |    |   Direct   |
|  SDK  |     |    SDK    |   |   Client   |    |    IPC     |
+-------+     +-----------+   +------------+    +------------+
```

### Browser Core

The browser core is built on a custom CEF (Chromium Embedded Framework) compiled from patched Chromium source:

- Multi-process architecture (browser, renderer, GPU processes).
- Off-screen rendering for headless operation.
- IPC via Unix domain sockets or stdin/stdout pipes.
- Context isolation with independent cookie jars and fingerprints.
- Up to 256 concurrent browser contexts.

### Stealth Layer (Chromium Source-Level)

All fingerprint spoofing is implemented as C++ modifications compiled directly into Chromium's Blink renderer:

- 27 C++ override modules covering navigator, canvas, WebGL, audio, fonts, WebRTC, timezone, and more.
- 31 minimal hook patches that wire Chromium source files to the spoofing overlay.
- VirtualMachine profiles define complete browser identities (delivered via CEF IPC).
- Spoofed values come from the same Blink code paths as real values — undetectable by JS introspection.
- Worker coverage: Dedicated, Shared, and Service Workers receive per-context configs.

### AI Layer

On-device AI for intelligent automation:

- OwlLlamaServer manages model lifecycle.
- OwlSemanticMatcher finds elements by description.
- OwlNLA executes natural language commands.
- OwlAIIntelligence provides page analysis.

### Media Layer

Video and image capture:

- OwlVideoRecorder captures to MP4 via FFmpeg.
- OwlLiveStreamer provides MJPEG streams.
- Shared memory frame buffer for efficient capture.
- Native screenshot capture with zoom support.

---

# Owl Browser — Company & Team Credentials

Source: https://owlbrowser.net/team/

Owl Browser is built and operated by Olib AI.

### Leadership Team
- **Tyonna M. (CEO)**: Former Vice President of Operations at JP Morgan Chase. Tyonna directs corporate compliance, financial operations, and growth strategy.
- **Akram H. S. (Founder & CTO)**: Previously Lead Software Developer at Aloha. Akram oversees core development, Chromium engine compiler patches, fingerprint virtualization, and low-level C++ module design.
- **Fakrul H. S. (Co-Founder)**: Venture co-founder supporting long-term organizational vision.
- **Maya M. (Chief Architect of AI)**: Maya directs on-device model deployment, llama.cpp fine-tuning, element matcher architectures, and semantic task processing.
- **Michael H. (Business Growth Advisor)**: A seasoned business advisor with a focus on growth strategies and enterprise software scaling.

### Corporate Location & Contact Details
- **Entity**: Olib AI (https://olib.ai)
- **Headquarters**: Stone Mountain, Georgia, United States
- **Official Contact Points**:
  - Technical & Customer Support: support@olib.ai
  - Enterprise Sales: sales@olib.ai
  - Vulnerability Disclosure: security@olib.ai
  - Primary Domain: https://owlbrowser.net/

---

# Owl Browser — Security, Compliance & Bug Bounty Program

Source: https://owlbrowser.net/security/

Security is a core design principle for Owl Browser. As a self-hosted engine, all automation runs within your control boundary.

## Security & SOC2 Aligned Controls
- **On-Device Cryptography**: AES-256-GCM encryption is used on-device for context data and local license configurations.
- **Memory Protection**: Implements `mlock` to pin browser context secrets in RAM, preventing them from being written to swap space where they could be dumped.
- **Minimal Privilege**: Executable within non-root Docker containers (UID 1000).
- **Read-Only Container Filesystem**: Supports running on read-only filesystems, preventing permanent malware persistence or disk tampering.
- **Zero Telemetry**: All data pathways remain fully local. No network traffic or execution analytics are phoned home to Olib servers.

## Bug Bounty Program
We run a vulnerability disclosure program with rewards ranging from $1,000 to $5,000 for critical security reports.
- Reports should be submitted to security@olib.ai, optionally encrypted using our PGP public keys.
- Response time SLA: Initial triage within 24 hours.

---

# Owl Browser — Production Case Studies & Testimonials

Our customers run automated browsers at scale for critical workloads.

## Case Study 1: Logistics & Invoicing (GC Transport Inc)
- **Customer**: Dariece, CEO of GC Transport Inc
- **Outcome**: "At GC Transportation, our dispatchers and managers rely on dozens of different portals to track trucks, manage rides, and handle operations. Deploying Owl Browser across our enterprise was a game-changer. It securely integrates with our internal tools to automate repetitive tasks like invoicing, driver billing, and logistics routing. Owl Browser gave us our time back."

## Case Study 2: E-commerce Lifecycle Automation (LaFrique Market)
- **Customer**: Ibrahim, CEO of LaFrique Market
- **Outcome**: "Managing the backend of LaFrique Market used to require constant tab-switching between our website dashboard, vendor portals, and accounting software. With Owl Browser, we've automated the entire retail lifecycle. From the moment a customer places an order, Owl instantly processes the invoice, updates our stock levels, and even alerts our vendors. It has completely streamlined our daily operations."

---

# Owl Browser — Independent Benchmark Reports

Source: https://owlbrowser.net/benchmark/

Owl Browser is regularly tested against leading anti-bot detection suites to verify our source-level stealth capabilities. Anyone can run these benchmarks locally to verify the results.

## Benchmark Results

| Test Suite / Detector | Playwright (Default) | Puppeteer (Default) | Owl Browser |
|-----------------------|----------------------|---------------------|-------------|
| **CreepJS**           | Flagged (F Rating)   | Flagged (F Rating)  | Passed (A+ Rating) |
| **Cloudflare Turnstile** | Blocked / CAPTCHA | Blocked / CAPTCHA  | Bypassed seamlessly |
| **Akamai Bot Manager** | Detected            | Detected            | Bypassed seamlessly |
| **DataDome**          | Blocked (100% rate)  | Blocked (100% rate) | Bypassed seamlessly |
| **PerimeterX**        | Detected            | Detected            | Bypassed seamlessly |

## Key Verification Proofs

- **No JS Hook Artifacts**: Unlike JS injection overlays, our fingerprint modification runs natively in Blink's C++ layer. Prototype checks and `toString()` verification return authentic results.
- **Hardware-Consistent WebGL**: Real GPU profiles (Intel, NVIDIA, AMD, Apple Silicon) are emulated in CEF C++ and pass shader precision and extension list consistency tests.
- **Timezone & Locale Sync**: Timezone, locale, and geographic coordinates are automatically synchronized with the exit IP address of the proxy (or Tor network node) to prevent mismatch flags.

## How to Run the Benchmarks Locally

Our benchmark scripts and verification tools are completely open-source. To audit our anti-detection results, follow these steps:

1. Clone the detection test repository:
   ```bash
   git clone https://github.com/Olib-AI/owl-detection-report.git
   ```
2. Follow the setup instructions in the README to execute the benchmark suite against a running Owl Browser instance or comparison browser.
3. Access the interactive test results page locally or visit our public hosted reports at https://owlbrowser.net/benchmark/.

---

# Owl Browser — Proxy and Privacy Routing

Source: https://owlbrowser.net/proxy/

## Not a Proxy Provider

Owl Browser is a browser automation engine. It does not operate a proxy network, sell proxy bandwidth, or provide IP addresses. The routing features described here use infrastructure you own or the Tor network, not Olib servers.

## Built-in Tor Control

Owl Browser ships with a built-in Tor controller. Each browser context can be given its own independent Tor circuit, so multiple sessions running in parallel get distinct exit nodes and never share identity across contexts. You do not need to install or manage a separate Tor binary; the browser handles the lifecycle automatically.

Key properties:
- Per-context circuits: every browser context gets its own Tor circuit. Parallel sessions never share an exit node or mix traffic.
- No extra setup: activate Tor for a context by passing is_tor=true when calling browser_create_context.
- Automatic teardown: closing a context closes its circuit. There is no residual connection state between sessions.

## Owl Sidecar

Owl Sidecar turns a device you already own into a private residential exit for Owl Browser. You install it on a home machine, a VPS, or any server you control, pair it to your Owl account with a short code, and your browser can route contexts through that device. The traffic goes directly from the browser to the sidecar. It never passes through Olib servers.

Because the exit is a device you own running on a connection you control, the traffic looks like an ordinary connection from that location. The sidecar opens a normal outbound connection to each target and forwards raw bytes, preserving the browser's own TLS handshake end to end. There is no added header, no rewrite, and nothing on the wire that marks the traffic as proxied.

How the connection works:
- Peer to peer: the browser and the sidecar connect directly. Olib runs a small coordination service to help the two sides find each other, then steps out of the path. Your data never touches Olib servers.
- No open ports required: the sidecar makes an outbound connection only. It works from a home network behind NAT with no port forwarding needed.
- Paired to your account: a device is usable only by browsers signed in to the same Owl account. A key is generated on the device during pairing and never leaves it.
- You stay in control: enable, disable, or remove a device from the portal at any time.

Supported platforms: macOS (Apple Silicon), Windows (x64), Linux (x64 and arm64).

Download: https://github.com/Olib-AI/owl-sidecar

## Bring Your Own Proxy

If you already have a proxy subscription from a third-party provider, Owl Browser accepts standard HTTP, HTTPS, and SOCKS5 proxies. Set a proxy per context so that different automation sessions use different exit addresses. See browser_set_proxy and browser_connect_proxy in the API reference.

---

# Owl Browser — SDKs, Deployment & License Tiers

## Deployment & Container Setup

The production deployment runs as a Docker container with s6-overlay managing four services:

| Service | Type | Description |
|---------|------|-------------|
| `owl-init-config` | oneshot | Secrets injection, TLS setup, license validation |
| `tor` | longrun | TOR SOCKS proxy (port 9050) and control (port 9051) |
| `owl-http-server` | longrun | HTTP API server with embedded browser process |
| `nginx` | longrun | Reverse proxy, TLS termination, serves React panel |

```bash
# Build with BuildKit secrets (required)
DOCKER_BUILDKIT=1 docker build \
  --secret id=owl_nonce_hmac_secret,src=./secrets/nonce_hmac_secret.txt \
  --secret id=owl_vm_profile_db_pass,src=./secrets/vm_profile_db_pass.txt \
  -t olib-browser:latest -f docker/Dockerfile .
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OWL_HTTP_TOKEN` | *required* | Bearer token for API authentication |
| `OWL_PANEL_PASSWORD` | *required* | Control panel login password |
| `OWL_HTTP_PORT` | 8080 | HTTP server port (internal) |
| `OWL_PANEL_PORT` | 80 | Nginx port (external) |
| `OWL_TLS_ENABLED` | true | Enable HTTPS |
| `OWL_DEV_MODE` | false | Disable auth and TLS validation |

## SDKs & Integration

### Node.js SDK (@olib-ai/owl-browser-sdk)
- **Version**: 2.0.4 | **Min Node**: 18.0.0
- **Install**: `npm install @olib-ai/owl-browser-sdk`

### Python SDK (owl-browser)
- **Version**: 2.0.4 | **Min Python**: 3.12
- **Install**: `pip install owl-browser`

### API Access Methods

**HTTP REST API**
```
POST /execute/{tool_name}
Authorization: Bearer <token>
Content-Type: application/json

{"param1": "value1", "param2": "value2"}
```

**WebSocket**
```json
{"id": 1, "method": "browser_navigate", "params": {"context_id": "ctx_1", "url": "https://example.com"}}
```

## License Types

| Type | Description |
|------|-------------|
| Trial | 14-day $0.99 evaluation license with the same access tier as Developer |
| Starter | Monthly subscription (3 seats) |
| Business | Annual license (10 seats) |
| Enterprise | Annual license (50 seats, priority support) |
| Developer | Individual developer license |

Contact: sales@olib.ai

---

# Owl Browser — Agent Skills Reference

Complete reference for AI agents to automate browsers using Owl Browser.

name: owl-browser
description: Automates browsers using Owl Browser, a high-performance browser engine with 178+ tools for web navigation, element interaction, text extraction, screenshots, fingerprint management, CAPTCHA solving, proxy management, video recording, and cookie management.
compatibility: Requires a running Owl Browser instance (Docker or native). Network access needed to connect to the Owl Browser HTTP server.
version: "1.3.1"
website: https://www.owlbrowser.net

## Core Concepts

- **Context**: An isolated browser instance with its own fingerprint, cookies, and proxy. Create with `browser_create_context`, close with `browser_close_context`. Every tool call (except context creation/listing) requires a `context_id`.
- **Tool**: An atomic browser action (navigate, click, type, screenshot, etc.). Execute via SDK methods or REST `POST /execute/{tool_name}`.
- **Flow**: A JSON sequence of tool steps executed in order with variable resolution and expectations. Portable across SDKs.
- **Antidetect**: Each context gets a unique, realistic browser fingerprint (canvas, WebGL, audio, fonts, navigator, etc.) from a database of 100+ real device profiles.
- **Smart Selectors**: Any tool that takes a `selector` parameter accepts three formats — the browser auto-detects which one you're using:
  - **CSS selector**: `#submit-btn`, `.nav-link`, `input[name=email]`
  - **Coordinates**: `100x200` (clicks at x=100, y=200)
  - **Natural language**: `login button`, `email input`, `search icon`

  Natural language selectors use a built-in semantic matcher that scores page elements by text similarity, ARIA labels, placeholders, and visual context — no CSS inspection required. Prefer natural language when you don't know the exact selector; use CSS when you need precision.

## Environment Setup

Store your connection settings in a `.env` file (never commit this file):

```bash
# .env
OWL_ENDPOINT=https://your-domain.com
OWL_TOKEN=your-secret-token
```

## Python SDK

### Installation

```bash
pip install owl-browser python-dotenv
```

### Async Usage (Recommended)

```python
import os, asyncio
from dotenv import load_dotenv
from owl_browser import OwlBrowser, RemoteConfig

load_dotenv()

async def main():
    config = RemoteConfig(
        url=os.environ["OWL_ENDPOINT"],
        token=os.environ["OWL_TOKEN"]
    )

    async with OwlBrowser(config) as browser:
        ctx = await browser.create_context()
        context_id = ctx["context_id"]

        await browser.navigate(context_id=context_id, url="https://example.com")
        await browser.wait_for_network_idle(context_id=context_id)
        await browser.click(context_id=context_id, selector="button#submit")
        # Natural language selector — no need to inspect DOM
        await browser.type(context_id=context_id, selector="email input", text="user@example.com")
        screenshot = await browser.screenshot(context_id=context_id)
        text = await browser.extract_text(context_id=context_id, selector="h1")
        markdown = await browser.get_markdown(context_id=context_id)
        await browser.close_context(context_id=context_id)

asyncio.run(main())
```

## Node.js SDK

### Installation

```bash
npm install @olib-ai/owl-browser-sdk dotenv
```

### Quick Start

```typescript
import 'dotenv/config';
import { OwlBrowser } from '@olib-ai/owl-browser-sdk';

const browser = new OwlBrowser({
  url: process.env.OWL_ENDPOINT!,
  token: process.env.OWL_TOKEN!,
  apiPrefix: ''  // '' for direct, '/api' for nginx proxy
});

await browser.connect();

const ctx = await browser.createContext();
const contextId = ctx.context_id;

await browser.navigate({ context_id: contextId, url: 'https://example.com' });
await browser.waitForNetworkIdle({ context_id: contextId });
await browser.click({ context_id: contextId, selector: 'button#submit' });
// Natural language — semantic matcher finds the right element
await browser.type({ context_id: contextId, selector: 'email input', text: 'user@example.com' });
const screenshot = await browser.screenshot({ context_id: contextId });
const markdown = await browser.getMarkdown({ context_id: contextId });
await browser.closeContext({ context_id: contextId });
await browser.close();
```

## REST API (Direct)

```
Authorization: Bearer <your-token>

POST /api/execute/{tool_name}
Content-Type: application/json
```

```bash
# Create context
curl -X POST -H "Authorization: Bearer $OWL_TOKEN" \
  -H "Content-Type: application/json" \
  $OWL_ENDPOINT/execute/browser_create_context

# Navigate
curl -X POST -H "Authorization: Bearer $OWL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context_id": "ctx_000001", "url": "https://example.com"}' \
  $OWL_ENDPOINT/execute/browser_navigate

# Screenshot
curl -X POST -H "Authorization: Bearer $OWL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context_id": "ctx_000001"}' \
  $OWL_ENDPOINT/execute/browser_screenshot
```

## Flow JSON Format

Flows are portable JSON files that define a sequence of browser automation steps. They work with both the Python and Node.js SDKs.

```json
{
  "name": "My Automation Flow",
  "description": "Description of what this flow does",
  "steps": [
    {
      "type": "browser_navigate",
      "url": "https://example.com"
    },
    {
      "type": "browser_wait_for_network_idle"
    },
    {
      "type": "browser_type",
      "selector": "#email",
      "text": "user@example.com"
    },
    {
      "type": "browser_click",
      "selector": "#submit"
    },
    {
      "type": "browser_extract_text",
      "selector": ".result",
      "expected": {
        "contains": "Success"
      }
    }
  ]
}
```

Use `${prev}` to reference the previous step's result:
```json
{"type": "browser_navigate", "url": "${prev.url}/about"}
```

Supported expectations: `equals`, `contains`, `length`, `greaterThan`, `lessThan`, `notEmpty`, `matches`, `field`.

## Tools Reference

Tool name mapping:
- REST API / Flow JSON: use as-is (e.g., `browser_navigate`)
- Python SDK: strip `browser_` prefix → `navigate(context_id=cid, url=...)`
- Node.js SDK: strip `browser_` prefix, camelCase or snake_case → `browser.navigate({context_id, url})`

All browser tools require `context_id` (string) as first param. Exceptions: `browser_create_context`, `browser_list_contexts`, and all `http_*` tools.

### Context Management
- `browser_create_context` — Create a new isolated browser context with its own cookies, storage, fingerprint, and optional proxy/LLM configuration. Params: llm_enabled, llm_use_builtin, llm_endpoint, llm_model, llm_api_key, profile_path, proxy_type, proxy_host, proxy_port, proxy_username, proxy_password, proxy_stealth, is_tor, resource_blocking, os, gpu, timezone, screen_size
- `browser_go` — One-shot browser navigation. Creates a new context, navigates, extracts content, closes context. Params: url (required), wait_until, timeout, output, os, use_tor
- `browser_close_context` — Close a browser context and release all resources
- `browser_list_contexts` — List all currently active browser contexts

### Agent Rendering
- `browser_observe` — Observe page state in OwlMark: compact, handle-addressable structured text view. Params: delta (boolean)
- `browser_expand` — Re-serialize one collapsed region, dedup template, or handle at higher detail. Params: handle (string, required), selector (string)
- `browser_read_node` — Read raw accessible name, value, description, and attributes for one handle. Params: handle (string, required), selector (string)

### Navigation
- `browser_navigate` — Navigate to a URL. Params: url (required), wait_until, timeout
- `browser_reload` — Reload the current page. Params: ignore_cache, wait_until, timeout
- `browser_go_back` — Navigate back in history. Params: wait_until, timeout
- `browser_go_forward` — Navigate forward in history. Params: wait_until, timeout
- `browser_can_go_back` — Check if navigation back is possible
- `browser_can_go_forward` — Check if navigation forward is possible
- `browser_set_content` — Set the page's HTML content directly. Params: html (required)

### Interaction
- `browser_click` — Click an element via CSS selector, XY coordinates, or natural language. Params: selector (required), hold_ms, index
- `browser_type` — Type text with human-like keystroke simulation. Params: selector, text (required), index
- `browser_pick` — Select an option from a dropdown. Params: selector (required), value (required)
- `browser_press_key` — Press a keyboard key. Params: key (required)
- `browser_submit_form` — Submit the focused form
- `browser_drag_drop` — Drag from start to end coordinates. Params: start_x, start_y, end_x, end_y (all required), mid_points
- `browser_html5_drag_drop` — HTML5 drag and drop using DragEvent. Params: source_selector (required), target_selector (required)
- `browser_mouse_move` — Move mouse along a natural curved path. Params: start_x, start_y, end_x, end_y (all required), steps, stop_points
- `browser_hover` — Hover over an element. Params: selector (required), index
- `browser_double_click` — Double-click an element. Params: selector (required), index
- `browser_right_click` — Right-click (context menu). Params: selector (required), index
- `browser_clear_input` — Clear text from an input field. Params: selector (required), index
- `browser_focus` — Set focus to an element. Params: selector (required), index
- `browser_blur` — Remove focus from an element. Params: selector (required)
- `browser_select_all` — Select all text in an input. Params: selector (required)
- `browser_keyboard_combo` — Press a key combination with modifiers. Params: combo (required)
- `browser_upload_file` — Upload files to a file input. Params: selector (required), file_paths (required)

### Content Extraction
- `browser_extract_text` — Extract visible text from page or element. Params: selector, regex, regex_group, index
- `browser_screenshot` — Capture PNG screenshot. Params: mode (viewport/element/fullpage), selector, scale
- `browser_highlight` — Visually highlight an element. Params: selector (required), border_color, background_color, index
- `browser_show_grid_overlay` — Display XY coordinate grid overlay. Params: horizontal_lines, vertical_lines, line_color, text_color
- `browser_get_html` — Extract HTML with configurable cleaning levels. Params: selector, clean_level (minimal/basic/aggressive)
- `browser_get_markdown` — Convert page content to clean Markdown. Params: include_links, include_images, max_length
- `browser_extract_site` — Crawl multiple pages of a website. Params: url (required), depth, max_pages, follow_external, output_format, include_images, include_metadata, exclude_patterns, timeout_per_page
- `browser_extract_site_progress` — Get progress of a site extraction job. Params: job_id (required)
- `browser_extract_site_result` — Get result of a completed extraction job. Params: job_id (required)
- `browser_extract_site_cancel` — Cancel a running extraction job. Params: job_id (required)
- `browser_extract_json` — Extract structured data as JSON. Params: template, selector
- `browser_detect_site` — Identify the type of website currently loaded
- `browser_list_templates` — List all available JSON extraction templates

### AI / LLM Tools
- `browser_summarize_page` — Generate structured AI summary of current page. Params: force_refresh
- `browser_query_page` — Ask a natural language question about page content. Params: query (required)
- `browser_llm_status` — Check if the LLM is ready to use
- `browser_nla` — Execute complex automation using natural language commands. Params: command (required)
- `browser_ai_click` — Click an element described in natural language using AI vision. Params: description (required)
- `browser_ai_type` — Type text into element described in natural language using AI vision. Params: description (required), text (required)
- `browser_ai_extract` — Extract specific information from the page using AI. Params: what (required)
- `browser_ai_query` — Ask a natural language question about the current page. Params: query (required)
- `browser_ai_analyze` — Perform comprehensive AI analysis of the current page
- `browser_find_element` — Find elements using natural language description. Params: description (required), max_results

### Scroll
- `browser_scroll_by` — Scroll by specified pixels. Params: y (required), x, verification_level
- `browser_scroll_to_element` — Scroll to bring element into view. Params: selector (required), index
- `browser_scroll_to_top` — Scroll to the top of the page
- `browser_scroll_to_bottom` — Scroll to the bottom of the page

### Wait
- `browser_wait_for_selector` — Wait for element to appear. Params: selector (required), timeout, index
- `browser_wait` — Pause execution for fixed milliseconds. Params: timeout (required)
- `browser_wait_for_network_idle` — Wait for network to be idle. Params: idle_time, timeout
- `browser_wait_for_function` — Wait for JavaScript condition. Params: js_function (required), polling, timeout
- `browser_wait_for_url` — Wait for URL to match pattern. Params: url_pattern (required), is_regex, timeout

### Page Info & Viewport
- `browser_get_page_info` — Get URL, title, meta, dimensions of current page
- `browser_get_page_map` — Get compact structured map of all interactive elements on the page. Params: intent, max_elements, region
- `browser_set_viewport` — Set viewport size. Params: width (required), height (required)
- `browser_reset_viewport` — Reset viewport to VM profile default
- `browser_zoom_in` — Zoom in 10%
- `browser_zoom_out` — Zoom out 10%
- `browser_zoom_reset` — Reset zoom to 100%
- `browser_get_console_log` — Read browser console logs. Params: level, filter, limit
- `browser_clear_console_log` — Clear all console logs

### Element Inspection
- `browser_is_visible` — Check if element is visible. Params: selector (required), index
- `browser_is_enabled` — Check if element is enabled. Params: selector (required), index
- `browser_is_checked` — Check if checkbox/radio is checked. Params: selector (required), index
- `browser_is_editable` — Check if element is editable. Params: selector (required), index
- `browser_count_elements` — Count elements matching a CSS selector. Params: selector (required)
- `browser_dispatch_event` — Dispatch a DOM event on an element. Params: selector (required), event_type (required), bubbles
- `browser_get_attribute` — Get HTML attribute value. Params: selector (required), attribute (required), index
- `browser_get_bounding_box` — Get position and size of element. Params: selector (required), index
- `browser_evaluate` — Execute arbitrary JavaScript. Params: script, expression, return_value
- `browser_get_element_at_position` — Get DOM element at XY coordinates. Params: x (required), y (required)
- `browser_get_interactive_elements` — Find all interactive elements on the page
- `browser_get_blocker_stats` — Get ad/tracker/analytics blocking statistics

### Clipboard
- `browser_clipboard_read` — Read text from system clipboard
- `browser_clipboard_write` — Write text to system clipboard. Params: text (required)
- `browser_clipboard_clear` — Clear the system clipboard

### Frames
- `browser_list_frames` — List all frames and iframes on the page
- `browser_switch_to_frame` — Switch to an iframe. Params: frame_selector (required)
- `browser_switch_to_main_frame` — Switch back to the main frame

### Video Recording
- `browser_start_video_recording` — Begin recording browser session. Params: fps, codec
- `browser_pause_video_recording` — Pause recording
- `browser_resume_video_recording` — Resume recording
- `browser_stop_video_recording` — Stop and save recording
- `browser_get_video_recording_stats` — Get recording statistics
- `browser_download_video_recording` — Get download URL for recording
- `browser_start_live_stream` — Start MJPEG live stream. Params: fps, quality
- `browser_stop_live_stream` — Stop live stream
- `browser_get_live_stream_stats` — Get live stream statistics
- `browser_list_live_streams` — List all active live streams
- `browser_get_live_frame` — Get latest frame as base64 image

### CAPTCHA
- `browser_detect_captcha` — Detect if page has a CAPTCHA
- `browser_classify_captcha` — Identify the type of CAPTCHA
- `browser_solve_text_captcha` — Solve text-based CAPTCHA via OCR. Params: max_attempts
- `browser_solve_image_captcha` — Solve image-selection CAPTCHA. Params: max_attempts, provider
- `browser_solve_captcha` — Auto-detect and solve any CAPTCHA type. Params: max_attempts, provider

### Cookies
- `browser_get_cookies` — Get all cookies. Params: url
- `browser_set_cookie` — Set a cookie. Params: url (required), name (required), value (required), domain, path, secure, httpOnly, sameSite, expires
- `browser_delete_cookies` — Delete cookies. Params: url, cookie_name
- `browser_get_headers` — Get HTTP response headers. Params: url

### Proxy
- `browser_set_proxy` — Configure proxy settings. Params: type (required), host (required), port (required), username, password, stealth, block_webrtc, spoof_timezone, spoof_language, is_tor
- `browser_get_proxy_status` — Get current proxy configuration and status
- `browser_connect_proxy` — Enable and connect the configured proxy
- `browser_disconnect_proxy` — Disable proxy and revert to direct connection
- `browser_set_timezone` — Override timezone at runtime. Params: timezone (required)

### Profiles
- `browser_create_profile` — Create new profile with randomized fingerprints. Params: name
- `browser_load_profile` — Load saved profile into context. Params: profile_path (required)
- `browser_save_profile` — Save context state to profile. Params: profile_name (required)
- `browser_download_profile` — Download a saved profile file. Params: profile_name (required)
- `browser_get_profile` — Get current profile state as JSON
- `browser_update_profile_cookies` — Update profile with current cookies
- `browser_get_context_info` — Get context info including VM profile and fingerprint hashes

### Network Interception
- `browser_add_network_rule` — Add interception rule. Params: url_pattern (required), action (required: allow/block/mock/redirect), is_regex, redirect_url, mock_body, mock_status, mock_content_type
- `browser_remove_network_rule` — Remove a rule by ID. Params: rule_id (required)
- `browser_enable_network_interception` — Enable/disable interception. Params: enable (required)
- `browser_get_network_log` — Get captured network requests log
- `browser_get_network_rules` — List all interception rules
- `browser_clear_network_log` — Clear network log entries
- `browser_enable_network_logging` — Enable/disable logging. Params: enable (required)

### Downloads
- `browser_set_download_path` — Configure download directory. Params: path (required)
- `browser_get_downloads` — List all downloads with status
- `browser_get_active_downloads` — Get in-progress downloads
- `browser_wait_for_download` — Wait for download to complete. Params: download_id (required), timeout
- `browser_cancel_download` — Cancel an in-progress download. Params: download_id (required)

### Dialogs
- `browser_set_dialog_action` — Configure automatic dialog handling. Params: dialog_type (required: alert/confirm/prompt/beforeunload), action (required: accept/dismiss/accept_with_text), prompt_text
- `browser_get_pending_dialog` — Check for pending JavaScript dialogs
- `browser_get_dialogs` — Get all dialog events in context
- `browser_handle_dialog` — Manually handle a dialog. Params: dialog_id (required), accept (required), response_text
- `browser_wait_for_dialog` — Wait for dialog to appear. Params: timeout

### Tabs
- `browser_get_tabs` — List all tabs in context
- `browser_switch_tab` — Switch to a tab. Params: tab_id (required)
- `browser_close_tab` — Close a tab. Params: tab_id (required)
- `browser_new_tab` — Open a new tab. Params: url
- `browser_get_active_tab` — Get the currently active tab
- `browser_get_tab_count` — Get number of open tabs
- `browser_get_blocked_popups` — Get list of blocked popup URLs
- `browser_set_popup_policy` — Configure popup handling. Params: policy (required: allow/block/new_tab/background)

### Demographics
- `browser_get_demographics` — Get user demographics based on IP geolocation
- `browser_get_location` — Get geographic location from IP
- `browser_get_datetime` — Get current date, time, and day of week
- `browser_get_weather` — Get current weather for detected location

### License
- `browser_get_license_status` — Check license validity
- `browser_get_license_info` — Get license details and seat information
- `browser_get_hardware_fingerprint` — Get hardware fingerprint for license binding
- `browser_add_license` — Add/activate a license. Params: license_content (required)

### HTTP Client Tools (No context_id required)
- `http_request` — Make HTTP/HTTPS request. Params: url (required), method, headers, body, cookies, auth_type, auth_username, auth_password, auth_token, proxy_type, proxy_host, proxy_port, use_tor, follow_redirects, timeout, ssl_verify, user_agent, output
- `http_download` — Download file from URL. Params: url (required), output_path, headers, proxy_type, proxy_host, proxy_port, use_tor, timeout, resume, user_agent
- `http_session_create` — Create persistent HTTP session with cookie management. Params: headers, user_agent, follow_redirects, ssl_verify, proxy_type, proxy_host, proxy_port, use_tor
- `http_session_request` — Make request in a persistent session. Params: session_id (required), url (required), method, headers, body, auth_type, timeout, output
- `http_session_get_cookies` — Get session cookies. Params: session_id (required), url
- `http_session_set_cookies` — Import cookies into session. Params: session_id (required), cookies (required)
- `http_session_close` — Close and destroy a session. Params: session_id (required)
- `http_session_list` — List all active HTTP sessions

---

# Owl Browser — Python SDK

Async-first Python SDK for Owl Browser automation with dynamic OpenAPI method generation and flow execution support.

## Features

- **Dynamic Method Generation**: Methods are automatically generated from the OpenAPI schema
- **Async-First Design**: Built with asyncio for optimal performance
- **Sync Wrappers**: Convenience methods for non-async code
- **Flow Execution**: Execute test flows with variable resolution and expectations
- **Type Safety**: Full type hints with Python 3.12+ features
- **Connection Pooling**: Efficient HTTP connection management
- **Retry Logic**: Automatic retries with exponential backoff

## Installation

```bash
pip install owl-browser
```

For development:

```bash
pip install owl-browser[dev]
```

## Quick Start

### Connection Modes

```python
from owl_browser import OwlBrowser, RemoteConfig

# Production (via nginx proxy) - this is the default
# Uses /api prefix: https://your-domain.com/api/execute/...
config = RemoteConfig(
    url="https://your-domain.com",
    token="your-token"
)

# Development (direct to http-server on port 8080)
# No prefix: http://localhost:8080/execute/...
config = RemoteConfig(
    url="http://localhost:8080",
    token="test-token",
    api_prefix=""  # Empty string for direct connection
)
```

### Async Usage (Recommended)

```python
import asyncio
from owl_browser import OwlBrowser, RemoteConfig

async def main():
    config = RemoteConfig(
        url="https://your-domain.com",
        token="your-secret-token"
    )

    async with OwlBrowser(config) as browser:
        ctx = await browser.create_context()
        context_id = ctx["context_id"]

        await browser.navigate(context_id=context_id, url="https://example.com")
        await browser.click(context_id=context_id, selector="button#submit")
        screenshot = await browser.screenshot(context_id=context_id)
        text = await browser.extract_text(context_id=context_id, selector="h1")
        print(f"Page title: {text}")
        await browser.close_context(context_id=context_id)

asyncio.run(main())
```

### Sync Usage

```python
from owl_browser import OwlBrowser, RemoteConfig

config = RemoteConfig(
    url="http://localhost:8080",
    token="your-secret-token"
)

browser = OwlBrowser(config)
browser.connect_sync()

ctx = browser.execute_sync("browser_create_context")
browser.execute_sync("browser_navigate", context_id=ctx["context_id"], url="https://example.com")
browser.execute_sync("browser_close_context", context_id=ctx["context_id"])

browser.close_sync()
```

## Authentication

### Bearer Token

```python
config = RemoteConfig(
    url="http://localhost:8080",
    token="your-secret-token"
)
```

### JWT Authentication

```python
from owl_browser import RemoteConfig, AuthMode, JWTConfig

config = RemoteConfig(
    url="http://localhost:8080",
    auth_mode=AuthMode.JWT,
    jwt=JWTConfig(
        private_key_path="/path/to/private.pem",
        expires_in=3600,  # 1 hour
        refresh_threshold=300,  # Refresh 5 minutes before expiry
        issuer="my-app",
        subject="user-123"
    )
)
```

## Flow Execution

```python
from owl_browser import OwlBrowser, RemoteConfig
from owl_browser.flow import FlowExecutor

async def run_flow():
    async with OwlBrowser(RemoteConfig(...)) as browser:
        ctx = await browser.create_context()
        executor = FlowExecutor(browser, ctx["context_id"])

        flow = FlowExecutor.load_flow("test-flows/navigation.json")
        result = await executor.execute(flow)

        if result.success:
            print(f"Flow completed in {result.total_duration_ms:.0f}ms")
            for step in result.steps:
                print(f"  [{step.step_index}] {step.tool_name}: {'OK' if step.success else 'FAIL'}")
        else:
            print(f"Flow failed: {result.error}")

        await browser.close_context(context_id=ctx["context_id"])
```

## Error Handling

```python
from owl_browser import (
    OwlBrowserError,
    ConnectionError,
    AuthenticationError,
    ToolExecutionError,
    TimeoutError,
)

try:
    async with OwlBrowser(config) as browser:
        await browser.navigate(context_id="invalid", url="https://example.com")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e.message}")
except TimeoutError as e:
    print(f"Operation timed out: {e}")
except ConnectionError as e:
    print(f"Connection failed: {e}")
```

## Configuration Options

```python
from owl_browser import RemoteConfig, RetryConfig

config = RemoteConfig(
    url="https://your-domain.com",
    token="secret",
    timeout=30.0,  # seconds
    max_concurrent=10,
    retry=RetryConfig(
        max_retries=3,
        initial_delay_ms=100,
        max_delay_ms=10000,
        backoff_multiplier=2.0,
        jitter_factor=0.1
    ),
    api_prefix="/api",  # Default: "/api" (production); "" for direct connection
    verify_ssl=True
)
```

## Requirements

- Python 3.12+
- aiohttp >= 3.9.0
- pyjwt[crypto] >= 2.8.0
- cryptography >= 42.0.0

## Links

- Website: https://www.owlbrowser.net
- Documentation: https://www.owlbrowser.net/docs
- GitHub: https://github.com/Olib-AI/owl-light (Free Browser Core)

---

# Owl Browser — Node.js SDK

Node.js SDK v2 for Owl Browser — AI-native browser automation with antidetect capabilities.

## Features

- **Async-first design** — All operations are async/await based
- **Dynamic method generation** — 144+ browser tools available as typed methods
- **OpenAPI schema bundled** — Works offline, no need to fetch schema from server
- **Flow execution engine** — Run complex automation flows with conditions and expectations
- **JWT and Token auth** — Flexible authentication options
- **TypeScript support** — Full type definitions included
- **Retry with backoff** — Built-in retry logic with exponential backoff and jitter

## Installation

```bash
npm install @olib-ai/owl-browser-sdk
```

## Quick Start

```typescript
import { OwlBrowser, RemoteConfig } from '@olib-ai/owl-browser-sdk';

const browser = new OwlBrowser({
  url: 'http://localhost:8080',
  token: 'your-secret-token',
  apiPrefix: ''  // Use '' for direct connection, '/api' for nginx proxy
});

await browser.connect();

const ctx = await browser.createContext();
const contextId = ctx.context_id;

await browser.navigate({ context_id: contextId, url: 'https://example.com' });
await browser.click({ context_id: contextId, selector: 'button#submit' });
const screenshot = await browser.screenshot({ context_id: contextId });
await browser.closeContext({ context_id: contextId });

await browser.close();
```

## Configuration

```typescript
interface RemoteConfig {
  // Required
  url: string;                    // Server URL (e.g., 'http://localhost:8080')

  // Authentication (one required)
  token?: string;                 // Bearer token for TOKEN auth
  authMode?: AuthMode;            // 'token' (default) or 'jwt'
  jwt?: JWTConfig;                // JWT configuration for JWT auth

  // Optional
  transport?: TransportMode;      // 'http' (default) or 'websocket'
  timeout?: number;               // Request timeout in seconds (default: 30)
  maxConcurrent?: number;         // Max concurrent requests (default: 10)
  retry?: RetryConfig;            // Retry configuration
  verifySsl?: boolean;            // Verify SSL certificates (default: true)
  apiPrefix?: string;             // API prefix (default: '/api', use '' for direct)
}
```

### JWT Authentication

```typescript
import { OwlBrowser, AuthMode } from '@olib-ai/owl-browser-sdk';

const browser = new OwlBrowser({
  url: 'http://localhost:8080',
  authMode: AuthMode.JWT,
  jwt: {
    privateKeyPath: '/path/to/private.pem',
    expiresIn: 3600,        // Token validity in seconds
    refreshThreshold: 300,   // Refresh when < 300s remaining
    issuer: 'my-app',
    claims: { custom: 'data' }
  }
});
```

## Dynamic Methods

The SDK dynamically generates methods for all 144+ browser tools. Methods are available in both camelCase and snake_case:

```typescript
// These are equivalent
await browser.createContext();
await browser.create_context();

// Navigation
await browser.navigate({ context_id: ctx, url: 'https://example.com' });
await browser.reload({ context_id: ctx });
await browser.goBack({ context_id: ctx });
await browser.goForward({ context_id: ctx });

// Interaction
await browser.click({ context_id: ctx, selector: '#button' });
await browser.type({ context_id: ctx, selector: '#input', text: 'Hello' });

// Data extraction
await browser.getHtml({ context_id: ctx });
await browser.getMarkdown({ context_id: ctx });
await browser.screenshot({ context_id: ctx });

// AI-powered tools
await browser.queryPage({ context_id: ctx, question: 'What is the title?' });
await browser.solveCaptcha({ context_id: ctx });
await browser.findElement({ context_id: ctx, description: 'login button' });
```

## Flow Execution

```typescript
import { OwlBrowser, FlowExecutor } from '@olib-ai/owl-browser-sdk';

const browser = new OwlBrowser({ url: '...', token: '...' });
await browser.connect();

const ctx = await browser.createContext();
const executor = new FlowExecutor(browser, ctx.context_id);

const flow = FlowExecutor.loadFlow('test-flows/navigation.json');
const result = await executor.execute(flow);

if (result.success) {
  console.log('Flow completed in', result.totalDurationMs, 'ms');
} else {
  console.error('Flow failed:', result.error);
}
```

### Conditional Branching

```json
{
  "type": "condition",
  "condition": {
    "source": "previous",
    "operator": "equals",
    "field": "success",
    "value": true
  },
  "onTrue": [
    { "type": "browser_click", "selector": "#continue" }
  ],
  "onFalse": [
    { "type": "browser_screenshot" }
  ]
}
```

## Error Handling

```typescript
import {
  OwlBrowserError,
  ConnectionError,
  AuthenticationError,
  ToolExecutionError,
  TimeoutError,
  RateLimitError,
  ElementNotFoundError
} from '@olib-ai/owl-browser-sdk';

try {
  await browser.click({ context_id: ctx, selector: '#nonexistent' });
} catch (e) {
  if (e instanceof ElementNotFoundError) {
    console.log('Element not found:', e.selector);
  } else if (e instanceof TimeoutError) {
    console.log('Operation timed out after', e.timeoutMs, 'ms');
  } else if (e instanceof RateLimitError) {
    console.log('Rate limited. Retry after', e.retryAfter, 'seconds');
  } else if (e instanceof AuthenticationError) {
    console.log('Auth failed:', e.message);
  }
}
```

## Advanced Usage

### OpenAPI Schema Access

```typescript
import { OpenAPILoader, getBundledSchema } from '@olib-ai/owl-browser-sdk';

const schema = getBundledSchema();
console.log('API Version:', schema.info.version);

const loader = new OpenAPILoader(schema);
for (const [name, tool] of loader.tools) {
  console.log(name + ':', tool.description);
}
```

## API Reference

### OwlBrowser

- `connect(): Promise<void>` — Connect to server
- `close(): Promise<void>` — Close connection
- `execute(toolName, params): Promise<unknown>` — Execute any tool
- `healthCheck(): Promise<HealthResponse>` — Check server health
- `listTools(): string[]` — List all tool names
- `listMethods(): string[]` — List all method names
- `getTool(name): ToolDefinition | undefined` — Get tool definition

### FlowExecutor

- `execute(flow): Promise<FlowResult>` — Execute a flow
- `abort(): void` — Abort current execution
- `reset(): void` — Reset abort flag
- `static loadFlow(path): Flow` — Load flow from JSON file
- `static parseFlow(data): Flow` — Parse flow from object

## Requirements

- Node.js 18+
- TypeScript 5+ (optional, for type definitions)

## Links

- **Website**: https://www.owlbrowser.net
- **Documentation**: https://www.owlbrowser.net/docs
- **GitHub**: https://github.com/Olib-AI/owl-light (Free Browser Core)
- **Support**: support@olib.ai

---

# Owl Browser — Changelog & Release Notes

All notable changes and release notes for Owl Browser.

## v1.2.0 (2026-06-10) — Agent Rendering
**Highlights:**
- New `render_mode='agent'`: the page returns as OwlMark, a compact, handle-addressable view built for AI agents instead of human eyes.
- `browser_observe`, `browser_expand`, `browser_read_node`: see a page, then click and type by stable handle token, with no CSS selectors and no pixel coordinates.
- MCP server now defaults to a lean, agent-native toolset and promotes the observe-and-act loop, with profile-scoped tool lists via `OWL_MCP_PROFILE`.
- Encrypted profile export now round-trips: a downloaded profile restores fingerprint and session cookies on the same install.

**Detailed Changes:**
- **Feature (Agent Rendering)**: `render_mode` on `browser_create_context`, one of 'pixel' (default), 'agent', or 'both'. In agent mode the page is serialized into OwlMark, a compact hierarchical text view of what is actually rendered, with a handle table of every interactive element. On a Hacker News front page this is 753 tokens with 240 clickable handles, versus roughly 1,365 tokens for a screenshot the model still has to decode and aim at.
- **Feature (Observe API)**: `browser_observe` returns the OwlMark render, the handle table, page metadata, and a token estimate, and blocks until the page is ready. `browser_expand` re-serializes one collapsed region or template at higher detail, and `browser_read_node` returns the full uncompacted text of a single node.
- **Feature (Interaction)**: Click and type by the handle token (for example b3, l5, x2) returned by `browser_observe`, with truthful action results so the agent knows whether a click actually navigated, changed the DOM, or did nothing. No coordinate guessing and no misfire retries.
- **Feature (Outline)**: `detail='outline'` on `browser_observe` returns a headings-only map of long reference pages, for cheap 'find the section' navigation before reading the full content.
- **Improvement (MCP Server)**: The MCP server now advertises a curated, profile-scoped toolset via the new `OWL_MCP_PROFILE` setting (agent, automation, webdev, or full). The default agent profile exposes only the short observe-and-act loop plus screenshot.
- **Improvement (Boilerplate folding)**: Token reductions across content and documentation pages from the agent renderer's compaction: boilerplate folding, template dedup, code-block compaction, and link-river collapse keep page renders well under screenshot cost.
- **Fix (Profile Export)**: Encrypted profile export (`browser_download_profile`) now round-trips.
- **Fix (Context Response)**: `browser_create_context` responses no longer include a duplicate `context_id` key.

## v1.1.2 (2026-05-11) — Owl Light & Version Pinning
**Highlights:**
- Owl Light: free to download Chrome replacement for Playwright and Puppeteer ([GitHub repository](https://github.com/Olib-AI/owl-light)).
- Pin contexts to specific Chrome major versions (143 through 148).
- Flow Designer 2.0: HTTP/FTP steps, capture & extract, variable picker, in-designer tutorial.
- Navigation and concurrent-session performance improvements.

**Detailed Changes:**
- **Feature (Owl Light)**: A free to download Chrome-replacement browser that speaks the Playwright and Puppeteer protocols, so existing scripts can switch from upstream Chrome to Owl with a single binary swap. Carries the same stealth, fingerprinting, and profile system as the full Owl Browser, with a lighter footprint targeted at automation workloads. Available at https://github.com/Olib-AI/owl-light.
- **Feature (Chrome Pinning)**: Chrome major version pinning on `browser_create_context` via the new `chrome_version_major` parameter (one of '143' to '148').
- **Feature (Flows)**: Flow Designer 2.0 with a new Network/HTTP step category exposing `http_request`, `http_download`, `http_session_*`, and `ftp_*` tools.
- **Improvement (Performance)**: Navigation pipeline and concurrent-session performance tuned end-to-end. 100 parallel sessions now reach the steady state in roughly 2 seconds.

## v1.1.1 (2026-04-16) — Multi-Process Architecture
- **Feature (Multi-Process)**: Multiple browser processes run in parallel, each handling its own set of contexts.
- **Feature (UUID Context IDs)**: Context IDs now use a UUID-based format (timestamp + sequence + random) instead of sequential counters to eliminate ID collisions in multi-process mode.
- **Feature (Detection Benchmarks)**: Open-source detection benchmarks published at https://github.com/Olib-AI/owl-detection-report.

## v1.1.0 (2026-03-24) — Custom CEF Build
- **Feature (Custom CEF)**: CEF is now compiled directly from Chromium source instead of using pre-compiled open-source builds, enabling deep engine-level stealth patches.
- **Fix (Tools)**: Fixed `browser_get_page_map` and `browser_get_markdown` reliability on complex page layouts.

## v1.0.11 (2026-03-03) — WebMCP Support
- **Feature (WebMCP)**: Web pages can now declare callable tools via `navigator.modelContext.registerTool()`. Added WebMCP tools: `browser_webmcp_get_tools`, `browser_webmcp_call_tool`, `browser_webmcp_refresh_tools`, and `browser_webmcp_get_all_tools`.
- **Feature (Search)**: New `browser_search` one-shot web search tool.

## v1.0.10 (2026-02-24) — Web Bot Auth
- **Feature (WBA)**: Built-in Web Bot Auth (RFC 9421) with Ed25519 signatures. Register as a Cloudflare Signed Agent.

## v1.0.0 (2025-10-15) — Initial Release
- **Feature (Initial Release)**: 150+ browser automation tools, enterprise-grade stealth technology, TypeScript SDK and HTTP API.

---

# Owl Browser — Independent Benchmark Reports

Owl Browser is regularly tested against leading anti-bot detection suites to verify our source-level stealth capabilities. Anyone can run these benchmarks locally to verify the results.

## Benchmark Results

| Test Suite / Detector | Playwright (Default) | Puppeteer (Default) | Owl Browser |
|-----------------------|----------------------|---------------------|-------------|
| **CreepJS**           | Flagged (F Rating)   | Flagged (F Rating)  | Passed (A+ Rating) |
| **Cloudflare Turnstile** | Blocked / CAPTCHA | Blocked / CAPTCHA  | Bypassed seamlessly |
| **Akamai Bot Manager** | Detected            | Detected            | Bypassed seamlessly |
| **DataDome**          | Blocked (100% rate)  | Blocked (100% rate) | Bypassed seamlessly |
| **PerimeterX**        | Detected            | Detected            | Bypassed seamlessly |

## Key Verification Proofs

- **No JS Hook Artifacts**: Unlike JS injection overlays, our fingerprint modification runs natively in Blink's C++ layer. Prototype checks and `toString()` verification return authentic results.
- **Hardware-Consistent WebGL**: Real GPU profiles (Intel, NVIDIA, AMD, Apple Silicon) are emulated in CEF C++ and pass shader precision and extension list consistency tests.
- **Timezone & Locale Sync**: Timezone, locale, and geographic coordinates are automatically synchronized with the exit IP address of the proxy (or Tor network node) to prevent mismatch flags.

## How to Run the Benchmarks Locally

Our benchmark scripts and verification tools are completely open-source. To audit our anti-detection results, follow these steps:

1. Clone the detection test repository:
   ```bash
   git clone https://github.com/Olib-AI/owl-detection-report.git
   ```
2. Follow the setup instructions in the README to execute the benchmark suite against a running Owl Browser instance or comparison browser.
3. Access the interactive test results page locally or visit our public hosted reports at https://owlbrowser.net/benchmark.

---