sendblue-browser

sendblue-browser

Long-running stealth Chromium (patchright) exposed via a tiny REST API. One process, many named sessions, durable cookies, one-click purge, and a CDP url for Playwright/Puppeteer to attach. Passes typical Cloudflare Turnstile and similar low-friction checks; not for hostile scraping at scale.

Repo: https://github.com/sendblue-api/sendblue-browser-use

Is the daemon running?

curl -s http://127.0.0.1:8787/health

If you get a JSON { ok: true, ... } response, skip to "Drive a session". Otherwise:

# Local dev (Bun)
cd <path-to-sendblue-browser-use>
touch .env
if [ -z "${BROWSER_USE_API_KEY:-}" ] && grep -q '^BROWSER_USE_API_KEY=' .env; then
  export BROWSER_USE_API_KEY="$(grep '^BROWSER_USE_API_KEY=' .env | tail -1 | cut -d= -f2-)"
fi
export BROWSER_USE_API_KEY="${BROWSER_USE_API_KEY:-$(openssl rand -hex 32)}"
if grep -q '^BROWSER_USE_API_KEY=' .env; then
  sed -i.bak "s/^BROWSER_USE_API_KEY=.*/BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY/" .env && rm -f .env.bak
else
  printf '\nBROWSER_USE_API_KEY=%s\n' "$BROWSER_USE_API_KEY" >> .env
fi
bun src/index.ts &

# Docker
docker compose up -d

Wait ~3s, then re-check /health. For later shell commands, reload the token with source .env.

Auth

Every endpoint except /health requires a bearer token (BROWSER_USE_API_KEY env var):

Authorization: Bearer $BROWSER_USE_API_KEY

Treat the token as local browser/network control: a token holder can run page scripts and navigate Chromium to private or localhost services reachable from the daemon host.

Drive a session

TOKEN="Authorization: Bearer $BROWSER_USE_API_KEY"

# 1. Create a session. persistent=false exposes a CDP url; persistent=true backs to an on-disk profile.
curl -s -X POST http://127.0.0.1:8787/sessions \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"qa","persistent":false,"viewport":{"width":1440,"height":900}}'

# 2. Navigate. http/https only; file:// and chrome:// are rejected. timeoutMs default 30s.
curl -s -X POST http://127.0.0.1:8787/sessions/qa/navigate \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/","waitUntil":"networkidle","timeoutMs":15000}'

# 3. Screenshot. ?fullPage=true and ?selector=CSS supported. Returns image/png.
#    With NAV_SCREENSHOT_POLICY=headless (default), headed sessions skip automatic
#    nav screenshots to avoid visible capture flicker. Call this explicitly for headed evidence.
curl -s "http://127.0.0.1:8787/sessions/qa/screenshot?fullPage=true" \
  -H "$TOKEN" -o /tmp/shot.png

# 4. Eval JS in page. EXPRESSION FORM ONLY — wrap statements in an IIFE.
#    Body cap 200 kB. 422 if the eval throws inside the page.
curl -s -X POST http://127.0.0.1:8787/sessions/qa/script \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"(() => ({ title: document.title, h1: document.querySelector(\"h1\")?.innerText }))()"}'

# 5. Cookies (Playwright shape: name+value + url OR domain+path)
curl -s -X POST http://127.0.0.1:8787/sessions/qa/cookies \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"cookies":[{"name":"session","value":"abc","url":"https://example.com"}]}'
curl -s "http://127.0.0.1:8787/sessions/qa/cookies?url=https://example.com" -H "$TOKEN"

# 6. Console ring buffer (last N messages from page)
curl -s "http://127.0.0.1:8787/sessions/qa/console?limit=50" -H "$TOKEN"

# 7. Clear cookies + active-page storage but keep the session id
curl -s -X POST http://127.0.0.1:8787/sessions/qa/purge -H "$TOKEN"

# 8. Close + delete profile
curl -s -X DELETE http://127.0.0.1:8787/sessions/qa -H "$TOKEN"