# Browser Automation

This guide walks through common browser automation patterns with Chaser.

## Quick ephemeral scrape

The fastest path to a browser automation result -- create a throwaway session, do the work, and move on:

```typescript
import { chromium } from "playwright";

// Create an ephemeral browser session
const res = await fetch("https://api.chaser.sh/v1/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CHASER_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ session_type: "browser", ephemeral: true })
});
const session = await res.json();

// Connect and automate
const browser = await chromium.connectOverCDP(session.endpoints.control);
const page = await browser.newPage();
await page.goto("https://example.com");
const title = await page.title();
console.log(title);
await browser.close();
```

## Persistent browser workspace

When you need browser state (cookies, local storage) to persist across sessions:

```bash
# Create a browser workspace once
chaser workspaces create --session-type browser --name scraper --json

# Boot sessions against it -- state carries over
chaser browser --workspace scraper --json
```

## Queued browser jobs

For batch work, use the jobs API instead of managing sessions directly:

```bash
# Scrape a URL
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "browser.scrape",
    "input": {"url": "https://example.com", "selector": "h1"}
  }' | jq

# Execute sequential browser actions
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "browser.action",
    "input": {
      "session_id": "<session_id>",
      "actions": [
        {"method": "Page.navigate", "params": {"url": "https://example.com"}},
        {"method": "Page.screenshot", "params": {}}
      ]
    }
  }' | jq
```

## MCP browser tool for agents

AI agents can use the `browser` MCP tool to automate browsers without managing CDP connections:

```bash
# Step 1: Prepare a browser session
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {"ephemeral": true, "action": "prepare"}
    }
  }' | jq

# Step 2: Discover available tools
# (use the session_id from step 1)
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {"session_id": "<session_id>", "action": "discover"}
    }
  }' | jq

# Step 3: Call a specific browser tool
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 3,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {
        "session_id": "<session_id>",
        "action": "call",
        "method": "browser_navigate",
        "params": {"url": "https://example.com"}
      }
    }
  }' | jq
```

## Proxy configuration

Pass a `proxy` selector when creating browser sessions to route traffic through residential or datacenter proxies:

```bash
curl -sS "$CHASER_API_URL/v1/sessions" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_type": "browser", "ephemeral": true, "proxy": "us-residential"}' | jq
```

## Related

- [Browser Sessions](/docs/sessions/browser-sessions) -- session creation and CDP details
- [Jobs](/docs/platform/jobs) -- queued execution and scheduling
- [MCP Integration](/docs/developer-tools/mcp-integration) -- agent tool surface