# Owl Browser Documentation

Welcome to the developer and AI agent documentation for Owl Browser. Owl Browser is a high-performance, self-hosted Chromium/CEF engine designed specifically for automated browser tasks and autonomous AI agents.

## Architecture Overview

Owl Browser replaces brittle screenshot-based browser automation with native engine-level capabilities:
- **Source-Level Stealth**: 27 C++ override modules and 31 Chromium Blink engine patches compile anti-detection spoofing directly into native code paths (navigator, canvas, WebGL, WebRTC, fonts, and audio), completely bypassing JavaScript-based bot detectors.
- **Agent Rendering & OwlMark**: Compact hierarchical text representation with stable handle tokens (`@handle_12`) for every interactive element. Reduces token consumption by >50% compared to Chrome DevTools MCP and Playwright MCP.
- **On-Device Vision AI**: Embedded llama.cpp engine running Qwen3-VL-2B for local, privacy-preserving CAPTCHA solving (reCAPTCHA, hCaptcha, Turnstile) without third-party solve services.
- **Built-in MCP Server**: Streamable HTTP Model Context Protocol server served directly at `POST /mcp` without auxiliary processes.
- **Multi-Context Concurrency**: Up to 256 isolated parallel browser contexts with independent cookie jars, proxies, and fingerprint profiles with sub-12ms cold-start time.

---

## Quick Start

### 1. Run via Docker

Start a self-hosted instance of Owl Browser:

```bash
docker run -d \
  -p 9222:9222 \
  -e OWL_API_KEY="your-api-key" \
  --shm-size=2gb \
  olib-ai/owl-browser:latest
```

Verify service readiness:
```bash
curl http://localhost:9222/api/v1/status
```

### 2. Python SDK

Install the async client:
```bash
pip install owl-browser-sdk
```

Run an automated session with Agent Rendering:
```python
import asyncio
from owl_browser import BrowserClient

async def main():
    async with BrowserClient("http://localhost:9222", api_key="your-api-key") as client:
        # Create an isolated context in agent mode
        context = await client.create_context(render_mode="agent")
        page = await context.new_page()

        # Navigate stealthily
        await page.goto("https://example.com")

        # Observe page state as OwlMark text
        observation = await page.observe()
        print(observation.owlmark)

        # Interact by handle token
        await page.click("@handle_4")
        await context.close()

asyncio.run(main())
```

### 3. Node.js SDK

Install the TypeScript/JavaScript client:
```bash
npm install @olib-ai/owl-browser
```

Migrate Playwright-style workflows:
```typescript
import { BrowserClient } from "@olib-ai/owl-browser";

const client = new BrowserClient({
  url: "http://localhost:9222",
  apiKey: "your-api-key",
});

async function run() {
  const context = await client.createContext({ renderMode: "agent" });
  const page = await context.newPage();

  await page.goto("https://example.com");
  const observation = await page.observe();
  console.log(observation.owlmark);

  await page.click("@handle_4");
  await context.close();
}

run();
```

---

## Core Automation Capabilities

### 1. Browser Context Management
- `browser_create_context`: Create an isolated context with custom screen resolution, locale, user agent, and proxy configuration.
- `browser_destroy_context`: Terminate a session and release memory immediately.
- `browser_list_contexts`: Enumerate active sessions.

### 2. Navigation & State
- `browser_navigate`: Navigate to destination URL with network idle detection.
- `browser_get_url`: Retrieve current page URL.
- `browser_get_title`: Retrieve page document title.
- `browser_go_back` / `browser_go_forward` / `browser_reload`: History navigation.

### 3. Agent Observation & OwlMark
- `browser_observe`: Return structured OwlMark hierarchical DOM representation.
- `browser_get_page_map`: Compact token-efficient page outline for high-level planning.
- `browser_screenshot`: Capture viewport or element image when visual confirmation is required.

### 4. Element Interaction
- `browser_click`: Click elements using either handle tokens (`@handle_4`) or standard CSS selectors.
- `browser_type`: Enter text with human-like keypress jitter.
- `browser_select`: Select dropdown options.
- `browser_scroll`: Scroll viewports with smooth trajectory.

### 5. CAPTCHA & Security
- `browser_solve_captcha`: Trigger on-device vision model to resolve visible challenges.
- `browser_classify_captcha`: Detect presence and type of CAPTCHA wall.

---

## Protocols & Interfaces

- **MCP Server**: Connect MCP agents to `http://localhost:9222/mcp`. Supports tools discovery (`tools/list`), execution (`tools/call`), and SSE streaming.
- **REST API**: 187 operations documented in the [OpenAPI Specification](https://owlbrowser.net/openapi.json).
- **NLWeb Endpoint**: Natural language observation answering via `/ask`.

---

## Documentation Index

- [Authentication Guide](https://owlbrowser.net/docs/auth.md): Bearer authentication, tokens, and OAuth metadata.
- [API Reference](https://owlbrowser.net/api.md): REST endpoints and JSON envelopes.
- [Python SDK Guide](https://owlbrowser.net/python-sdk.md): Async Python SDK reference.
- [Node.js SDK Guide](https://owlbrowser.net/node-sdk.md): TypeScript / Node.js client documentation.
- [Agent Instructions](https://owlbrowser.net/agent-instructions.md): System prompt guidelines and error handling rules for LLMs.
- [Agent Flows](https://owlbrowser.net/agent-flows.md): Declarative JSON flow schema for zero-agent execution.
- [Pricing Plans](https://owlbrowser.net/pricing.md): Evaluation and production deployment pricing.
- [Documentation Index for Agents (llms.txt)](https://owlbrowser.net/docs/llms.txt): Scoped markdown index for LLMs.