sendblue-browser-use: Instructions file for Codex

AGENTS.md — sendblue-browser-use

Spec: https://agents.md. This file is read by Codex, Cursor, Antigravity, Windsurf, Aider, Cline, Jules, Zed, and most other agents that follow the convention.

What this repo is

A standalone HTTP daemon that runs a stealth-patched Chromium (patchright) for browser automation. Long-lived process, bearer-token-gated REST API, optional CDP attach for any client (Playwright, Puppeteer, custom scripts). Passes typical Cloudflare Turnstile and similar low-friction checks; not for hostile scraping at scale.

Source layout:

• src/ — Bun + Hono HTTP server
• mcp/ — MCP server wrapper (npm-publishable as sendblue-browser-mcp)
• skills/sendblue-browser/SKILL.md — cross-agent skill (Claude / Codex / Antigravity / Cline)
• .claude-plugin/plugin.json — Claude Code plugin manifest
• examples/ — Playwright / Puppeteer / multi-agent CDP attach snippets
• Dockerfile + docker-compose.yml — self-contained deploy

Setup

bun install
bun --bun x patchright install chromium
cp .env.example .env
# Set BROWSER_USE_API_KEY (any string ≥ 8 chars; generator: openssl rand -hex 32)
bun run dev          # starts daemon on http://127.0.0.1:8787

Or Docker: docker compose up -d.

Common commands

# Health (no auth)
curl -s http://127.0.0.1:8787/health

# Create a session
curl -s -X POST http://127.0.0.1:8787/sessions \
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"qa","persistent":false}'

# Navigate (http/https only)
curl -s -X POST http://127.0.0.1:8787/sessions/qa/navigate \
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/","waitUntil":"networkidle","timeoutMs":15000}'

# Screenshot
curl -s "http://127.0.0.1:8787/sessions/qa/screenshot?fullPage=true" \
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" -o /tmp/shot.png

# Eval JS — expression form (wrap statements in IIFE)
curl -s -X POST http://127.0.0.1:8787/sessions/qa/script \
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"(() => document.title)()"}'