Guides

Browser Automation

View as Markdown

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:

1import { chromium } from "playwright";
2
3// Create an ephemeral browser session
4const res = await fetch("https://api.chaser.sh/v1/sessions", {
5  method: "POST",
6  headers: {
7    "Authorization": `Bearer ${process.env.CHASER_API_KEY}`,
8    "Content-Type": "application/json"
9  },
10  body: JSON.stringify({ session_type: "browser", ephemeral: true })
11});
12const session = await res.json();
13
14// Connect and automate
15const browser = await chromium.connectOverCDP(session.endpoints.control);
16const page = await browser.newPage();
17await page.goto("https://example.com");
18const title = await page.title();
19console.log(title);
20await browser.close();

Persistent browser workspace

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

$# 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:

$# 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:

$# 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:

$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