Getting Started with Stealth Browser

Before you begin

You need:

A Geonode account with Stealth Browser access
An API key that works on staging
Staging base URL (use this for checks for now): https://stealth-staging-direct-zjk4365f7y54.geonode.com

Production is https://stealth.geonode.io. Do not treat prod as verified until activation works there.

Create a session

POST /v1/sessions?wait=true

wait=true (default) waits until the session is ready or failed (about 6 seconds). wait=false returns 202 with state: "starting"; poll GET /v1/sessions/{id} until ready or failed.

Example request

curl -X POST "https://stealth-staging-direct-zjk4365f7y54.geonode.com/v1/sessions?wait=true" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "us",
    "engine": "chromium",
    "ttl_seconds": 1800
  }'

Example response (sanitized)

Shape verified against a live create on staging. Tokens and IPs below are placeholders.

{
  "id": "aa11a2a310b4",
  "country": "us",
  "created_at": 1794583523.758,
  "expires_at": 1794583823.758,
  "state": "ready",
  "exit_ip": "203.0.113.10",
  "error": null,
  "engine": "chromium",
  "blocking": ["image", "font", "media"],
  "idle_timeout_seconds": 300,
  "live": true,
  "record": false,
  "webgl": "swiftshader",
  "proxy_bytes": 0,
  "connect_url": "https://stealth-staging-direct-zjk4365f7y54.geonode.com/<session-token>",
  "ws_url": "wss://stealth-staging-direct-zjk4365f7y54.geonode.com/<session-token>/devtools/browser/<browser-id>",
  "live_url": "https://stealth-staging-direct-zjk4365f7y54.geonode.com/<session-token>/live",
  "live_view_url": "https://stealth-staging-direct-zjk4365f7y54.geonode.com/<session-token>/live/view",
  "seconds_left": 295.8
}

The token inside connect_url is the credential. Anyone with that URL can drive the browser. Keep it on your server.

Connect from code

Chromium: use connect_url as the CDP endpoint (Playwright connectOverCDP, Puppeteer, or raw CDP).
Firefox: use the Playwright websocket from connect_url / ws_url (Firefox is a Playwright server, not CDP).

End the session

curl -X DELETE "https://stealth-staging-direct-zjk4365f7y54.geonode.com/v1/sessions/SESSION_ID" \
  -H "X-API-Key: YOUR_API_KEY"

A successful delete returns 204. An already-ended session returns 404. Refresh the session list instead of assuming it is still running.