Supernatural docs

Quick start

1. Sign in and go to Settings → API keys → New key. Copy the sk_… value — it's shown only once.
2. Settings → IP whitelist: add the public IP of the machine that will open CDP connections, or POST /api/v1/settings/ip-whitelist with {"ip":"current"} from that machine.
3. Start a session: POST /api/v1/sessions. Poll GET /api/v1/sessions/<id> until status="running" (typically 3–8s on a warm worker).
4. Connect any CDP client (Playwright, Puppeteer, chrome-remote-interface) to wss://api.supernatural.sh/api/v1/sessions/<id>/cdp. Do not use the cdp_url field from the response — that's an internal pointer.
5. Stop with DELETE /api/v1/sessions/<id>. For persistent sessions, wait for storage_status="synced" before resuming.

Authentication

Conventions & errors

• Timestamps are RFC 3339 UTC (2026-05-10T12:00:00Z).
• IDs are UUID v4 strings.
• Bodies use snake_case JSON; file uploads use multipart/form-data.
• Request body size is capped at 1 MiB (100 MiB on the file-upload route).
• DELETE endpoints return either {"status":"deleted"} or 204 No Content — both are success; the shape is documented per endpoint.

Every error response is {"error":"<reason>"} with an HTTP status. Some errors also carry a stable error code (e.g. payment_not_configured, no_payment_method) plus a human message. Status meanings used across the API:

• 400 — validation failure (bad enum, missing required field, conflicting parameters).
• 401 — missing or invalid Authorization.
• 402 — account is not active (no current subscription).
• 403 — authenticated, but blocked: plan limit (profiles), IP not in CDP whitelist, or unauthorized resource.
• 404 — resource not found (or not visible to your account — we don't distinguish to prevent enumeration).
• 409 — billing-state conflict (e.g. switching plans while past-due or mid-cancellation).
• 429 — rate limit, or plan-usage cap (concurrency, monthly minutes, persistent profiles, BYO-proxy plan check, bandwidth).
• 503 — transient infrastructure issue (no worker capacity, sidecar unreachable, billing provider not configured). Safe to retry with backoff.

Files

Move files in and out of a running session. Files live in tmpfs and are wiped when the container stops — sync anything you need to keep.

{
  "files": [
    { "name": "report.pdf",  "size": 245120, "kind": "download" },
    { "name": "invoice.pdf", "size": 12480,  "kind": "upload"   }
  ],
  "count": 2
}

curl https://api.supernatural.sh/api/v1/sessions/<id>/files/report.pdf \
  -H "Authorization: ApiKey sk_…" \
  -o report.pdf

curl -X POST \
  https://api.supernatural.sh/api/v1/sessions/<id>/files \
  -H "Authorization: ApiKey sk_…" \
  -F "file=@./document.pdf"

{
  "name": "document.pdf",
  "size": 245120,
  "path": "/home/chromium/Uploads/<session-id>/document.pdf"
}

CDP

Direct WebSocket access to Chrome DevTools Protocol. Authenticated by IP whitelist — the upgrade handshake can't carry an Authorization header reliably, so we authenticate by source IP instead.

Profiles

Reusable fingerprint configurations applied at session-create time. Profiles are templates; persistent sessions are state. The two are independent.

{ "profiles": [
  { "id": "…", "user_id": "…", "name": "scraper-eu", "os": "macos", "location": "Europe/Paris",
    "persona": "casual", "template_id": "macos-stealth-1",
    "config_json": { … }, "created_at": "…", "updated_at": "…" }
] }

{ "name": "scraper-eu-v2", "config_json": { … } }

Templates

Pre-built fingerprint bundles curated by Supernatural. Used as the basis for new profiles. Read-only — templates are managed server-side.

{ "templates": [
  { "id": "macos-stealth-1", "name": "macOS Stealth (default)",
    "os": "macos", "description": "…" }
] }

API keys

Programmatic-access tokens. Use the ApiKey scheme for SDK / MCP / direct REST clients. Bypasses must_change_password, so they keep working even while the password owner is mid-rotation. These endpoints accept JWT only — an API key cannot enumerate or rotate other API keys.

{ "api_keys": [
  {
    "id": "…",
    "name": "Automation",
    "key_prefix": "sk_57502",
    "last_used_at": "2026-05-18T10:14:00Z",
    "created_at": "2026-05-01T12:00:00Z",
    "revoked_at": null
  }
] }

{ "name": "Automation" }

{
  "id": "…",
  "name": "Automation",
  "key": "sk_2342fddcccbb91d8…",
  "key_prefix": "sk_2342f",
  "created_at": "2026-05-18T10:14:00Z"
}

IP whitelist

Source-IP allowlist for the CDP WebSocket. Required because the upgrade handshake can't reliably carry Bearer auth (browsers, transparent proxies). MCP and the REST API do NOT consult this list — only the raw /sessions/:id/cdp socket does.

{ "entries": [
  { "id": "…", "user_id": "…",
    "ip_address": "203.0.113.7",
    "label": "Office", "created_at": "…" }
] }

{ "ip": "current", "label": "My Office" }

Usage

Monthly hours and bandwidth metering, plus accrued overage charges.

{
  "total_minutes": 120,
  "plan_minutes": 180000,
  "overage_minutes": 0,
  "month": "2026-05-01",
  "plan": "pro_monthly",
  "usage_percentage": 0.07,
  "allow_hours_overage": true,
  "profile_count": 3,
  "max_profiles": 25,
  "bandwidth_rate_cents": 250,
  "hours_overage_rate_cents": 15,
  "bandwidth_bytes": 4823945,
  "bandwidth_charge_amount_cents": 0,
  "hours_overage_minutes": 0,
  "hours_overage_amount_cents": 0
}

{ "months": [
  { "month": "2026-04-01", "total_minutes": 1200,
    "plan_minutes": 180000, "overage_minutes": 0 }
] }

Account

Account profile, settings, and password rotation. Same surface the dashboard uses.

{
  "id": "…",
  "email": "[email protected]",
  "name": "Sam",
  "plan": "pro_monthly",
  "role": "user",
  "allow_hours_overage": true,
  "byo_proxy_only": false,
  "bandwidth_rate_cents": 250,
  "hours_overage_rate_cents": 15,
  "must_change_password": false,
  "email_verified": true,
  "account_status": "active",
  "oauth_provider": null,
  "created_at": "2026-04-01T00:00:00Z"
}

{ "allow_hours_overage": true, "byo_proxy_only": false }

{
  "message": "password updated",
  "access_token": "eyJ…",
  "refresh_token": "…",
  "token_type": "Bearer"
}

Billing

The only billing endpoint customer code should call directly is the public plan catalog. Subscription management (checkout, portal, invoices, cancel/reactivate, plan changes) runs through Stripe-hosted pages driven by the dashboard — there is no programmatic surface for it.

{ "plans": [
  {
    "id": "…",
    "name": "pro_monthly",
    "display_name": "Pro · Monthly",
    "minutes_per_month": 180000,
    "max_concurrent_sessions": 10,
    "max_profiles": 25,
    "bandwidth_rate_cents": 250,
    "hours_overage_rate_cents": 15,
    "price_cents": 19900,
    "is_default": false,
    "provider_plan_ids": { … }
  }
] }

Install

Python

pip install sprntrl
# Optional — for the Playwright helper:
pip install 'sprntrl[playwright]' && playwright install chromium

Node.js / TypeScript

npm install sprntrl
# Optional — pick whichever browser library you use:
npm install playwright
npm install puppeteer    # or puppeteer-core

Node requires >=18 (global fetch / FormData); for await using, Node >=24 and TypeScript >=5.2. Python requires >=3.9.

Configuration

Both SDKs read SPRNTRL_API_KEY from the environment by default. Override via the constructor. SPRNTRL_BASE_URL defaults to https://api.supernatural.sh. Auth uses the ApiKey scheme (same as the REST API and MCP).

Python

from sprntrl import Sprntrl, AsyncSprntrl

client = Sprntrl()                              # reads SPRNTRL_API_KEY
client = Sprntrl(api_key="sk_...")              # or pass explicitly
client = Sprntrl(timeout=30.0, max_retries=2)   # timeout in SECONDS

Node.js

import { Sprntrl } from "sprntrl";

const client = new Sprntrl();                                   // reads SPRNTRL_API_KEY
const client = new Sprntrl({ apiKey: "sk_..." });               // or pass explicitly
const client = new Sprntrl({ timeout: 30_000, maxRetries: 2 }); // timeout in MILLISECONDS

Quick start

The browser_session / browserSession helper is the fast path — it waits for the session to be ready, registers your IP (opt-in), connects Playwright, and tears the browser down on exit. The session itself stays alive — caller owns its lifecycle.

Python (sync)

from sprntrl import Sprntrl

with Sprntrl() as client:
    session = client.sessions.create(os="macos", location="America/New_York")

    # Context manager: waits, whitelists IP, connects, cleans up.
    with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
        page = browser.contexts[0].new_page()
        page.goto("https://bot.sannysoft.com")
        page.screenshot(path="out.png")

    client.sessions.stop(session["id"])

Node.js

import { Sprntrl } from "sprntrl";
import type { Browser } from "playwright";

const client = new Sprntrl();

const session = await client.sessions.create({ os: "macos", location: "America/New_York" });
const handle = await client.sessions.browserSession(session.id, { autoWhitelist: true });
try {
  const browser = handle.browser as Browser;
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://bot.sannysoft.com");
  await page.screenshot({ path: "out.png" });
} finally {
  await handle.close();
  await client.sessions.stop(session.id);
}

Python (async)

import asyncio
from sprntrl import AsyncSprntrl

async def main():
    async with AsyncSprntrl() as client:
        session = await client.sessions.create(os="macos", location="America/New_York")
        async with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
            page = await browser.contexts[0].new_page()
            await page.goto("https://example.com")
        await client.sessions.stop(session["id"])

asyncio.run(main())

Node.js — await using (Node 24+ / TS 5.2+)

import type { Browser } from "playwright";

{
  await using handle = await client.sessions.browserSession(session.id, { autoWhitelist: true });
  const browser = handle.browser as Browser;
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://example.com");
} // Symbol.asyncDispose closes the browser here

Puppeteer (Node only)

Pass framework: "puppeteer" to browserSession or connect. The SDK tries puppeteer-core first, then falls back to the full puppeteer package.

import { Sprntrl } from "sprntrl";
import type { Browser } from "puppeteer";

const client = new Sprntrl();
const session = await client.sessions.create({ os: "macos", location: "America/New_York" });

const handle = await client.sessions.browserSession(session.id, {
  framework: "puppeteer",
  autoWhitelist: true,
});
try {
  const browser = handle.browser as Browser;
  const [page] = await browser.pages();
  await page.goto("https://example.com");
} finally {
  await handle.close();
  await client.sessions.stop(session.id);
}

Session create — full parameters

Both SDKs accept the same options on sessions.create. Proxy can be a flat URL string or a dict / object — the SDK normalises both into the API's flat field shape.

Python

session = client.sessions.create(
    os="macos",                       # "macos" | "windows"
    location="America/New_York",
    persistent=True,                  # keep data dir across stop/resume
    session_name="invoice-scraper",   # required when persistent=True
    captcha_solver=True,              # spawn the NopeCHA-backed solver daemon
    isolated_world=False,             # opt out of stealth JS isolation (default True)
    proxy="http://user:pw@host:8080", # or ProxyConfig dict
)

Node.js

const session = await client.sessions.create({
  os: "macos",                          // "macos" | "windows"
  location: "America/New_York",
  persistent: true,
  session_name: "invoice-scraper",      // required when persistent: true
  captcha_solver: true,
  isolated_world: false,                // opt out of stealth JS isolation (default true)
  proxy: "http://user:pw@host:8080",    // or { protocol, host, port, username, password }
});

Lower-level helpers

If you want to manage the browser yourself, plug into a different CDP client, or escape the helpers entirely, use connect(), cdp_url() / cdpUrl(), or the raw request() escape hatch.

Python

# Returns a connected Playwright Browser — you own teardown.
browser = client.sessions.connect(session_id, auto_whitelist=True)
try:
    ...
finally:
    browser.close()

# Wait for status="running" without connecting:
client.sessions.wait_until_ready(session_id, timeout=60.0)

# Raw CDP WebSocket URL — hand to any CDP client.
url = client.sessions.cdp_url(session_id)
# wss://api.supernatural.sh/api/v1/sessions/<id>/cdp

Node.js

const browser = await client.sessions.connect(session.id, { autoWhitelist: true });
try { /* ... */ } finally { await (browser as { close(): Promise<void> }).close(); }

await client.sessions.waitUntilReady(session.id, { timeout: 60_000 });

const url = client.sessions.cdpUrl(session.id);
// wss://api.supernatural.sh/api/v1/sessions/<id>/cdp

// Low-level REST escape hatch for endpoints the SDK doesn't wrap:
const data = await client.request<{ foo: string }>({
  method: "GET",
  path: "/api/v1/some/route",
  query: { limit: 10 },
});

Resource reference

Identical surface in both SDKs (naming follows language conventions: snake_case in Python, camelCase in Node). Each tile shows the Python form / Node form.

Profiles

Profiles are reusable fingerprint configurations (distinct from persistent sessions, which keep the data dir). Create one from a server-side template, optionally overriding fields.

Python

templates = client.templates.list()
tpl = next(t for t in templates if t["os"] == "macos")

profile = client.profiles.create(
    name="scraper-eu",
    template_id=tpl["id"],
    description="EU residential, macOS persona",
    os="macos",
    location="Europe/Paris",
    persona="casual",        # optional behavioural persona
    config={...},            # optional config_json override
)

Node.js

const templates = await client.templates.list();
const tpl = templates.find((t) => t.os === "macos")!;

const profile = await client.profiles.create({
  name: "scraper-eu",
  template_id: tpl.id,
  description: "EU residential, macOS persona",
  os: "macos",
  location: "Europe/Paris",
  persona: "casual",
  config: { /* ... */ },
});

File transfer examples

File transfer is out-of-band: uploads land in the container at /home/chromium/Uploads/<session_id>/<name>, downloads come from Chrome's download dir. upload returns no value (raises / rejects on failure). Per-request limit 100 MB, per-session quota 500 MB.

Python

# Upload a local file — no return value; raises on error.
with open("invoice.pdf", "rb") as f:
    client.sessions.files.upload(session_id, "invoice.pdf", f)

# List files (union of Uploads/ and Downloads/):
for f in client.sessions.files.list(session_id):
    print(f["name"], f["size"])

# Download a file Chrome wrote:
data = client.sessions.files.download(session_id, "report.pdf")
with open("report.pdf", "wb") as out:
    out.write(data)

Node.js

import { readFile, writeFile } from "node:fs/promises";

// Upload — Promise<void>, throws on error.
await client.sessions.files.upload(
  session.id,
  "invoice.pdf",
  await readFile("invoice.pdf"),
);

// List + download (download returns ArrayBuffer):
const files = await client.sessions.files.list(session.id);
const data = await client.sessions.files.download(session.id, "report.pdf");
await writeFile("report.pdf", Buffer.from(data));

Error handling

Both SDKs expose a typed error hierarchy. Transient errors (5xx, 429, 409, 408, connection errors) are retried automatically up to max_retries / maxRetries with exponential backoff.

Python

from sprntrl import (
    Sprntrl,
    SprntrlError,             # base (also raised for non-HTTP failures)
    APIError,                 # status != 2xx (has .status and .body)
    BadRequestError,          # 400
    AuthenticationError,      # 401
    PermissionDeniedError,    # 403
    NotFoundError,            # 404
    ConflictError,            # 409
    UnprocessableEntityError, # 422
    RateLimitError,           # 429 — plan/concurrency/bandwidth caps live here
    InternalServerError,      # 5xx
    APIConnectionError, APIConnectionTimeoutError,
)

try:
    client.sessions.create(os="macos", location="America/New_York")
except RateLimitError as e:
    print("hit a plan limit:", e.body)
except APIError as e:
    print("api error:", e.status, e)

Node.js

import {
  SprntrlError,
  APIError,
  BadRequestError, AuthenticationError, PermissionDeniedError,
  NotFoundError, ConflictError, UnprocessableEntityError,
  RateLimitError, InternalServerError,
  APIConnectionError, APIConnectionTimeoutError,
} from "sprntrl";

try {
  await client.sessions.create({ os: "macos", location: "America/New_York" });
} catch (err) {
  if (err instanceof RateLimitError) console.log("hit a plan limit:", err.body);
  else if (err instanceof APIError)   console.log("api error", err.status, err.body);
  else throw err;
}

Python / Node parity at a glance

Gotchas

Endpoint & auth model

Setup by client

Cursor

Command Palette (Cmd/Ctrl+Shift+P) → "Open MCP Configuration File". Add:

{
  "mcpServers": {
    "sprntrl": {
      "url": "https://api.supernatural.sh/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

The Supernatural tools should appear in Cursor's MCP panel within a few seconds.

VS Code

Use any extension that speaks Streamable HTTP (the official Anthropic extension, Continue, etc.). Configure the server:

{
  "mcpServers": {
    "sprntrl": {
      "url": "https://api.supernatural.sh/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

Claude Code

Claude Code cannot speak Streamable HTTP directly today (its HTTP transport forces OAuth), so use the mcp-remote stdio bridge. Add to .claude.json under mcpServers:

{
  "mcpServers": {
    "sprntrl": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.supernatural.sh/mcp",
        "--header",
        "Authorization: ApiKey YOUR_API_KEY"
      ]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "sprntrl": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.supernatural.sh/mcp",
        "--header",
        "Authorization: ApiKey YOUR_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop. Tools appear under the plug icon.

Python / Node (programmatic)

Connect to the MCP server from your own code with the official MCP SDKs.

Python

pip install mcp

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async def main():
    async with streamablehttp_client(
        "https://api.supernatural.sh/mcp",
        headers={"Authorization": "ApiKey YOUR_API_KEY"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"Available tools: {len(tools.tools)}")

            res = await session.call_tool("session_create", {
                "os": "macos", "location": "America/New_York"
            })
            print(res.content[0].text)

asyncio.run(main())

Node.js

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.supernatural.sh/mcp"),
  { requestInit: { headers: { Authorization: "ApiKey YOUR_API_KEY" } } },
);
const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log("tools:", tools.tools.map((t) => t.name));

const res = await client.callTool({
  name: "session_create",
  arguments: { os: "macos", location: "America/New_York" },
});
console.log(res.content[0].text);

Tool reference

24 tools across six groups. Required parameters are marked *.

End-to-end walkthrough

A typical agent flow — find a piece of information on a website and screenshot the result:

# 1. Discover the IANA timezones the proxy pool serves
locations_list
# → { "locations": ["America/New_York","America/Los_Angeles","Europe/London", …], … }

# 2. Spin up a session
session_create { os: "macos", location: "America/New_York" }
# → { id: "9d8f…", status: "creating", … }

# 3. Poll until ready (3–8s on a warm worker)
session_info { session_id: "9d8f…" }
# → { status: "running", … }

# 4. Navigate
browser_navigate { session_id: "9d8f…", url: "https://news.ycombinator.com" }

# 5. Read the page structure
browser_snapshot { session_id: "9d8f…" }
# → - link "Top" [ref=12]
#   - article
#     - link "Show HN: …" [ref=42]

# 6. Click the first story (snapshot just before clicking — refs are fragile)
browser_click { session_id: "9d8f…", ref: 42 }

# 7. Pull the article text in readability mode
browser_content { session_id: "9d8f…", readability: true }

# 8. Capture proof
browser_screenshot { session_id: "9d8f…", filename: "hn-top.png" }

# 9. Tear it down (data dir is synced first for persistent sessions)
session_kill { session_id: "9d8f…" }

Stealth gotchas

Troubleshooting

Universal prerequisites

Every integration on this page assumes you have done these three things — the same regardless of framework, so we cover them once.

curl -X POST https://api.supernatural.sh/api/v1/settings/ip-whitelist \
  -H "Authorization: ApiKey $SPRNTRL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"current"}'

import os, time, httpx

API_KEY  = os.environ["SPRNTRL_API_KEY"]
BASE_URL = "https://api.supernatural.sh"
HEADERS  = {"Authorization": f"ApiKey {API_KEY}"}

def create_session_and_wait(timeout_s: float = 60.0) -> str:
    with httpx.Client(base_url=BASE_URL, headers=HEADERS, timeout=30.0) as http:
        r = http.post("/api/v1/sessions", json={"os": "macos", "location": "America/New_York"})
        r.raise_for_status()
        sid = r.json()["id"]

        deadline = time.monotonic() + timeout_s
        while time.monotonic() < deadline:
            s = http.get(f"/api/v1/sessions/{sid}").json()
            if s["status"] == "running":
                return sid
            if s["status"] in ("stopped", "failed"):
                raise RuntimeError(f"session entered terminal state: {s['status']}")
            time.sleep(0.5)
        raise TimeoutError("session did not become ready in time")

session_id = create_session_and_wait()
cdp_url    = f"wss://api.supernatural.sh/api/v1/sessions/{session_id}/cdp"

const API_KEY  = process.env.SPRNTRL_API_KEY!;
const BASE_URL = "https://api.supernatural.sh";
const HEADERS  = {
  "Authorization": `ApiKey ${API_KEY}`,
  "Content-Type":  "application/json",
};

async function createSessionAndWait(timeoutMs = 60_000): Promise<string> {
  const created = await fetch(`${BASE_URL}/api/v1/sessions`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ os: "macos", location: "America/New_York" }),
  });
  if (!created.ok) throw new Error(`create failed: ${created.status}`);
  const { id } = await created.json();

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const s = await (await fetch(`${BASE_URL}/api/v1/sessions/${id}`, { headers: HEADERS })).json();
    if (s.status === "running") return id;
    if (s.status === "stopped" || s.status === "failed") {
      throw new Error(`session entered terminal state: ${s.status}`);
    }
    await new Promise((r) => setTimeout(r, 500));
  }
  throw new Error("session did not become ready in time");
}

const sessionId = await createSessionAndWait();
const cdpUrl    = `wss://api.supernatural.sh/api/v1/sessions/${sessionId}/cdp`;

# Python
httpx.delete(f"{BASE_URL}/api/v1/sessions/{session_id}", headers=HEADERS)

// Node
await fetch(`${BASE_URL}/api/v1/sessions/${sessionId}`, { method: "DELETE", headers: HEADERS });

Playwright

Playwright connects to Supernatural with connect_over_cdp / connectOverCDP. The default browser context contains the page Supernatural already opened — use it directly.

Python

pip install playwright

import asyncio
from playwright.async_api import async_playwright

# session_id + cdp_url from step 2 above

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(cdp_url)
        try:
            context = browser.contexts[0]
            page    = context.pages[0] if context.pages else await context.new_page()

            await page.goto("https://bot.sannysoft.com")
            await page.screenshot(path="out.png")
            print(await page.title())
        finally:
            await browser.close()  # disconnects Playwright; session stays alive

asyncio.run(main())
# Remember to DELETE the session when you're done with it (step 3).

TypeScript / Node.js

npm install playwright

import { chromium } from "playwright";

// sessionId + cdpUrl from step 2 above

const browser = await chromium.connectOverCDP(cdpUrl);
try {
  const [context] = browser.contexts();
  const page      = context.pages()[0] ?? await context.newPage();

  await page.goto("https://bot.sannysoft.com");
  await page.screenshot({ path: "out.png" });
  console.log(await page.title());
} finally {
  await browser.close();
}

Puppeteer

Puppeteer attaches via puppeteer.connect. Use puppeteer-core — you don't need the bundled Chromium because Supernatural already runs one.

npm install puppeteer-core

import puppeteer from "puppeteer-core";

// sessionId + cdpUrl from step 2 above

const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl });
try {
  const [page] = await browser.pages();
  await page.goto("https://bot.sannysoft.com");
  console.log(await page.title());
} finally {
  await browser.disconnect();  // leaves Chrome running; stop the Supernatural session via the API
}

Browser-Use

Browser-Use is an LLM-driven browser agent. Point its Browser at the Supernatural CDP URL and hand it to an Agent.

pip install browser-use

import asyncio
from browser_use import Agent, Browser, ChatOpenAI

# session_id + cdp_url from step 2 above

async def main():
    browser = Browser(cdp_url=cdp_url)
    agent = Agent(
        task="Go to Hacker News and return the title of the top story.",
        llm=ChatOpenAI(model="gpt-4.1-mini"),
        browser=browser,
    )
    history = await agent.run()
    print(history.final_result())

asyncio.run(main())
# Stop the Supernatural session via the API afterwards (step 3).

Stagehand

Stagehand layers act/observe/extract on top of Playwright. Supernatural works with the TypeScript client's LOCAL mode, which accepts a cdpUrl in localBrowserLaunchOptions.

npm install @browserbasehq/stagehand

import { Stagehand } from "@browserbasehq/stagehand";

// sessionId + cdpUrl from step 2 above

const stagehand = new Stagehand({
  env: "LOCAL",
  modelName: "openai/gpt-4.1-mini",
  modelClientOptions: { apiKey: process.env.OPENAI_API_KEY },
  localBrowserLaunchOptions: { cdpUrl },
});

try {
  await stagehand.init();
  const page = stagehand.page;        // Playwright Page on the live tab

  await page.goto("https://news.ycombinator.com");

  const stories = await page.extract({
    instruction: "Extract the titles and URLs of the first 5 stories",
    schema: {
      type: "object",
      properties: {
        stories: {
          type: "array",
          items: {
            type: "object",
            properties: { title: { type: "string" }, url: { type: "string" } },
            required: ["title", "url"],
          },
        },
      },
      required: ["stories"],
    },
  });
  console.log(stories);

  await page.act("Click on the first story title");
} finally {
  await stagehand.close();  // closes the Playwright connection only
}

Any CDP client (chrome-remote-interface)

For low-level work, talk to the WebSocket directly. The endpoint is browser-level, so Target.*, Browser.*, and (per attached target) Page.* / DOM.* / Runtime.* / Network.* / Input.* are all available.

npm install chrome-remote-interface

import CDP from "chrome-remote-interface";

// sessionId + cdpUrl from step 2 above

const client = await CDP({ target: cdpUrl });
try {
  const { Page, Runtime } = client;

  await Page.enable();
  await Page.navigate({ url: "https://example.com" });
  await Page.loadEventFired();

  const { result } = await Runtime.evaluate({ expression: "document.title" });
  console.log(result.value);
} finally {
  await client.close();
}