> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Automation

> Low-level browser automation with stealth mode, CAPTCHA handling, and vision-based navigation

# Browser Automation

OrcBot's browser automation system provides production-ready web scraping and interaction capabilities with built-in anti-bot detection, CAPTCHA solving, and vision-based navigation.

<Warning>
  **Prefer high-level skills first.** Always try `web_search`, `http_fetch`, or `extract_article` before using low-level browser automation. Browser operations are slower and more resource-intensive.
</Warning>

## Architecture

### Browser Engines

OrcBot supports three browser engines:

1. **Puppeteer** (default) - Fast, reliable Chromium automation
2. **Playwright** - Advanced Chromium with better stealth
3. **Lightpanda** - Lightweight headless browser (experimental)

Switch engines with `switch_browser_engine`.

### Stealth Features

All browser operations include:

* `--disable-blink-features=AutomationControlled` flag removal
* Realistic user agent strings (desktop or mobile)
* Persistent profiles with cookies and localStorage
* Resource blocking (ads, trackers, analytics)
* Console log capture for debugging
* Blank page detection and recovery

### Persistent Profiles

Browser profiles are stored in `~/.orcbot/browser-profiles/` (Playwright) or `~/.orcbot/puppeteer-profiles/` (Puppeteer). Profiles persist:

* Cookies and session storage
* localStorage data
* Browser history
* Cached resources

Use `switch_browser_profile` to manage multiple identities.

## Core Navigation Skills

### browser\_navigate

Navigate to a URL and extract semantic snapshot. See [Web Search](/api/skills/web-search#browser_navigate) for full documentation.

### browser\_examine\_page

Get a semantic snapshot of the current page without navigating.

**Parameters:**

None.

**Return Value:**

Semantic snapshot identical to `browser_navigate` output, but for the current page.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_examine_page",
  "args": {}
}
```

**Metadata:**

* **isDeep**: `true`
* **isResearch**: `false`

<Tip>
  Use `browser_examine_page` after clicking links or submitting forms instead of navigating again. It's instant.
</Tip>

### browser\_back

Navigate back to the previous page in browser history.

**Parameters:**

None.

**Return Value:**

Confirmation message and new page URL.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_back",
  "args": {}
}
```

## Interaction Skills

### browser\_click

Click an element by CSS selector or reference number.

**Parameters:**

<ParamField path="selector_or_ref" type="string | number" required>
  CSS selector (e.g., `"#submit-btn"`) or reference number from snapshot (e.g., `3`)
</ParamField>

**Return Value:**

Confirmation message with element details.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_click",
  "args": {
    "selector_or_ref": "#login-button"
  }
}
```

**Using References:**

The semantic snapshot includes numbered references for interactive elements:

```
--- INTERACTIVE ELEMENTS ---
[0] button: "Login" (id=login-btn)
[1] link: "Forgot password?" (href=/reset)
[2] input: email (name=email)
```

Click by reference:

```json theme={null}
{
  "skill": "browser_click",
  "args": {
    "selector_or_ref": 0
  }
}
```

### browser\_type

Type text into an input field.

**Parameters:**

<ParamField path="selector_or_ref" type="string | number" required>
  CSS selector or reference number for the input element
</ParamField>

<ParamField path="text" type="string" required>
  Text to type
</ParamField>

<ParamField path="slow" type="boolean" default="false">
  Use slow typing (100ms delay per character) to avoid bot detection
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_type",
  "args": {
    "selector_or_ref": "input[name='username']",
    "text": "user@example.com",
    "slow": true
  }
}
```

### browser\_press

Press a keyboard key or key combination.

**Parameters:**

<ParamField path="key" type="string" required>
  Key name or combination (e.g., `"Enter"`, `"Control+C"`, `"Alt+Tab"`)
</ParamField>

**Supported Keys:**

* Single keys: `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `ArrowUp`, etc.
* Combinations: `Control+C`, `Meta+V`, `Shift+Enter`

**Example Usage:**

```json theme={null}
{
  "skill": "browser_press",
  "args": {
    "key": "Enter"
  }
}
```

### browser\_hover

Hover over an element to trigger menus or tooltips.

**Parameters:**

<ParamField path="selector" type="string" required>
  CSS selector for the element to hover
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_hover",
  "args": {
    "selector": ".dropdown-menu"
  }
}
```

### browser\_select

Select an option in a dropdown by visible label.

**Parameters:**

<ParamField path="selector" type="string" required>
  CSS selector for the `<select>` element
</ParamField>

<ParamField path="value" type="string" required>
  Visible label text of the option to select
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_select",
  "args": {
    "selector": "#country-dropdown",
    "value": "United States"
  }
}
```

### browser\_scroll

Scroll the page up or down.

**Parameters:**

<ParamField path="direction" type="string" required>
  `"up"` or `"down"`
</ParamField>

<ParamField path="amount" type="number" default="500">
  Pixels to scroll
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_scroll",
  "args": {
    "direction": "down",
    "amount": 1000
  }
}
```

## Waiting & Timing

### browser\_wait

Wait for a specified duration.

**Parameters:**

<ParamField path="ms" type="number" required>
  Milliseconds to wait
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_wait",
  "args": {
    "ms": 2000
  }
}
```

### browser\_wait\_for

Wait for an element to appear on the page.

**Parameters:**

<ParamField path="selector" type="string" required>
  CSS selector to wait for
</ParamField>

<ParamField path="timeout" type="number" default="30000">
  Timeout in milliseconds
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "browser_wait_for",
  "args": {
    "selector": ".search-results",
    "timeout": 10000
  }
}
```

## Visual & Analysis Skills

### browser\_screenshot

Capture a screenshot of the current page.

**Parameters:**

<ParamField path="fullPage" type="boolean" default="false">
  Capture entire page or just viewport
</ParamField>

**Return Value:**

File path to the saved screenshot.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_screenshot",
  "args": {
    "fullPage": true
  }
}
```

**Response Example:**

```
Screenshot saved to: /home/user/.orcbot/downloads/screenshot_1704123456789.png
```

### browser\_vision

Analyze the current page using AI vision (GPT-4 Vision or Gemini).

**Parameters:**

<ParamField path="prompt" type="string">
  Optional question or instruction. Defaults to "Describe what you see on this page."
</ParamField>

**Return Value:**

AI-generated description of the visual content.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_vision",
  "args": {
    "prompt": "What is the main call-to-action button on this page?"
  }
}
```

**Response Example:**

```
The main call-to-action button is a large blue button in the center of the page labeled "Start Free Trial". It features white text and a subtle shadow effect. Below the button is small gray text reading "No credit card required".
```

### browser\_solve\_captcha

Attempt to solve a detected CAPTCHA automatically.

**Parameters:**

None. Requires `captchaApiKey` (2captcha) in config.

**Return Value:**

Success or error message.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_solve_captcha",
  "args": {}
}
```

<Note>
  CAPTCHA solving requires an API key from [2captcha.com](https://2captcha.com) and can take 20-60 seconds.
</Note>

## Advanced Skills

### browser\_run\_js

Execute custom JavaScript on the current page.

**Parameters:**

<ParamField path="script" type="string" required>
  JavaScript code to execute. Returns the result of the expression.
</ParamField>

**Return Value:**

JSON-serialized result of the script.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_run_js",
  "args": {
    "script": "document.querySelectorAll('a').length"
  }
}
```

**Response Example:**

```
Script result: 47
```

**Complex Example:**

```json theme={null}
{
  "skill": "browser_run_js",
  "args": {
    "script": "Array.from(document.querySelectorAll('h2')).map(h => h.textContent)"
  }
}
```

### browser\_run\_script

Execute custom Puppeteer/Playwright code with access to `page` and `browser` objects. **(Admin only)**

**Parameters:**

<ParamField path="code" type="string" required>
  JavaScript code with access to `page` and `browser` variables
</ParamField>

**Return Value:**

Script output or error.

**Example Usage:**

```json theme={null}
{
  "skill": "browser_run_script",
  "args": {
    "code": "await page.setViewport({ width: 1920, height: 1080 }); return 'Viewport updated';"
  }
}
```

<Warning>
  `browser_run_script` is restricted to admin users only. It provides full access to the browser automation API.
</Warning>

## Profile & Engine Management

### switch\_browser\_profile

Switch to a different persistent browser profile.

**Parameters:**

<ParamField path="profileName" type="string" required>
  Name of the profile to switch to (creates if doesn't exist)
</ParamField>

<ParamField path="profileDir" type="string">
  Optional custom directory for profiles
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "switch_browser_profile",
  "args": {
    "profileName": "work"
  }
}
```

**Use Cases:**

* Manage multiple logged-in sessions
* Isolate scraping tasks
* Test with different browser states
* Bypass rate limits (different cookies/fingerprints)

### switch\_browser\_engine

Switch between Puppeteer, Playwright, and Lightpanda.

**Parameters:**

<ParamField path="engine" type="string" required>
  `"puppeteer"`, `"playwright"`, or `"lightpanda"`
</ParamField>

<ParamField path="endpoint" type="string">
  For Lightpanda: CDP endpoint (default: `ws://127.0.0.1:9222`)
</ParamField>

**Example Usage:**

```json theme={null}
{
  "skill": "switch_browser_engine",
  "args": {
    "engine": "playwright"
  }
}
```

## Mobile Viewport

Switch between desktop and mobile viewports:

```json theme={null}
{
  "skill": "set_viewport_mode",
  "args": {
    "mode": "mobile"
  }
}
```

**Mobile viewport specs:**

* Size: 375x812 (iPhone 13)
* User agent: iOS Safari 16.6
* Device scale factor: 2x
* Touch events enabled

## State Tracking

The browser maintains state across skills:

* **Last navigated URL**: Tracks the current page
* **Blank page counter**: Auto-recovers from blank pages (max 3 attempts)
* **Console logs**: Captures JavaScript errors and warnings
* **Intercepted APIs**: Records XHR/fetch requests (when enabled)

## Circuit Breaker Pattern

The browser implements automatic loop prevention:

* Tracks consecutive blank page loads per domain
* After 3 blank pages from the same domain, switches to headful mode
* Clears counter after successful navigation

## Best Practices

<Tip>
  **Navigation strategy for reliability:**

  1. Try `web_search` or `http_fetch` first
  2. If you must use the browser, start with `browser_navigate`
  3. Use references (numbered elements) instead of brittle CSS selectors
  4. Always call `browser_wait_for` before interacting with dynamic content
  5. Use `browser_examine_page` after interactions instead of re-navigating
</Tip>

<Warning>
  **Avoid these common mistakes:**

  * Don't navigate to the same URL twice in one action
  * Don't use `browser_click` + `browser_navigate` — just click and examine
  * Don't guess selectors — read the snapshot first
  * Don't skip `browser_wait_for` on SPAs (React, Vue, Angular)
</Warning>

## Troubleshooting

### "Element not found"

* **Cause**: Selector doesn't match or element hasn't loaded yet
* **Fix**: Use `browser_examine_page` to verify the selector, then `browser_wait_for` before clicking

### "Blank page detected"

* **Cause**: Site blocked automation or JavaScript failed to render
* **Fix**: Retry with `headless: false` or switch to a fresh profile

### "CAPTCHA blocked navigation"

* **Cause**: Site detected automation
* **Fix**: Configure `captchaApiKey` or use `switch_browser_profile` to a clean profile

### "Browser crashed"

* **Cause**: Out of memory or GPU issues
* **Fix**: Check browser args in config, disable extensions, or restart OrcBot

## Related Skills

<CardGroup cols={2}>
  <Card title="Web Search" icon="magnifying-glass" href="/api/skills/web-search">
    High-level search and navigation
  </Card>

  <Card title="Shell Execution" icon="terminal" href="/api/skills/shell">
    Execute system commands and scripts
  </Card>
</CardGroup>