Browserless SOP

Appearance

Test ​

Status: PASS (cloud API verified 2026-07-01) ​

Classification: NEEDS-ACCOUNT (cloud API key) or NEEDS-DESKTOP (Docker self-host) Install method: npm (server package) or Docker (self-host image) Cost tier: Free tier available on cloud; self-hosted is free with Docker What is required: Either a cloud API key from browserless.io OR Docker installed locally to run the server image

The npm package @browserless.io/browserless is the server itself, not a client SDK. Confirmed installed: @browserless.io/browserless@2.54.2. Running it still requires one of the two paths below.

Smoke test -- Docker self-hosted ​

Start the container (takes 30-60 seconds on first pull):

bash
docker run -p 3000:3000 ghcr.io/browserless/chromium

Then hit the health endpoint:

bash
curl http://localhost:3000/json/version

Expected success output:

json
{
  "Browser": "Chrome/...",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0 ...",
  "V8-Version": "...",
  "WebKit-Version": "...",
  "webSocketDebuggerUrl": "ws://localhost:3000"
}

A 200 response with a webSocketDebuggerUrl field confirms the WebSocket endpoint is live and ready for connections.

Also verify the interactive docs are reachable:

bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/docs
# Expected: 200

Smoke test -- Cloud (requires API key) ​

Run the REST screenshot endpoint with a known public URL:

bash
curl -X POST \
  "https://production-sfo.browserless.io/chromium/screenshot?token=$BROWSERLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.example.com"}' \
  --output /tmp/browserless-smoke.png && echo "SUCCESS: screenshot written"

Expected success output:

  % Total    % Received ...
SUCCESS: screenshot written

And /tmp/browserless-smoke.png is a valid PNG of example.com. A non-empty PNG file with no error body confirms authentication, WebSocket routing, and browser launch all worked.

What failure looks like ​

SymptomLikely cause
{"error":"Not authorized"}Wrong or missing API key
curl: (7) Failed to connectDocker not running / wrong port
Empty or zero-byte PNGBrowser crashed; check session timeout setting
HTTP 429Exceeded concurrent browser limit for your plan

Hetzner (server) verification ​

Date: 2026-07-01 Verified by: Automa (agent-runtime-hetzner-1, user merlino)

Verify command:

bash
ssh -o BatchMode=yes -o ConnectTimeout=15 agent-runtime-hetzner-1 \
  'source ~/fleet.env; curl -s -o /dev/null -w "browserless HTTP %{http_code}" \
  "https://production-sfo.browserless.io/json/version?token=$BROWSERLESS_API_KEY"'

Real output:

browserless HTTP 200

Status: PASS -- The Browserless cloud API is reachable from Hetzner. The token in ~/fleet.env ($BROWSERLESS_API_KEY) authenticated successfully and the /json/version endpoint returned HTTP 200.

Tested status ​

Cloud API verified live from Hetzner server 2026-07-01. HTTP 200 confirmed. tested=true.