SPHYNX
esc
  • Loading
Open console

Guides

Connect Puppeteer

Connect Puppeteer to a session's cdp_url with the session's own viewport.

At the end your Puppeteer script drives a hosted session instead of a local browser. You need an API key and puppeteer-core. No local browser is needed.

Create a session and connect

Create the session over HTTP, then pass its cdp_url as browserWSEndpoint. The URL carries its own token, so the connect call needs no headers.

TypeScript
import puppeteer from "puppeteer-core";

const base = process.env.SPHYNX_URL;
const headers = {
  Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${base}/v1/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ os: "windows" }),
});
const session = await created.json();

const browser = await puppeteer.connect({
  browserWSEndpoint: session.cdp_url,
  defaultViewport: null,
});
const [page] = await browser.pages();

await page.goto("https://example.com");
console.log(await page.title());

await browser.disconnect(); // the session keeps running
await fetch(`${base}/v1/sessions/${session.id}`, { method: "DELETE", headers });

The script prints the page title:

Output
Example Domain

Keep the fingerprint intact

The session already has a consistent identity. These rules keep it that way.

  • Pass defaultViewport: null. Without it Puppeteer resizes every page to 800 by 600, which no longer matches the rest of the session.
  • Use the pages of the default context: browser.pages() and browser.newPage(). A new browser context loses the session's identity and storage.
  • Do not set a user agent, locale or timezone from the client. The session already has consistent values.
  • Do not close the session's last page; open the new page first. A session with no page has no tabs, and drive calls answer tab_not_found until POST /v1/sessions/{id}/tabs opens one.

Disconnect, do not close

browser.disconnect() drops the connection and leaves the session running, with its pages and cookies. browser.close() tells the browser itself to exit, which ends the session with close reason browser_closed.

Reconnect

The token in cdp_url is valid for token_expires_in_seconds, 1800 when issued, and can be reused until then. After that, ask for a new URL with POST/v1/sessions/{id}/tokens and connect again.

TypeScript
const minted = await fetch(`${base}/v1/sessions/${session.id}/tokens`, {
  method: "POST",
  headers,
});
const { cdp_url } = await minted.json();

const browser = await puppeteer.connect({
  browserWSEndpoint: cdp_url,
  defaultViewport: null,
});
const [page] = await browser.pages(); // the page you left
200
{
  "cdp_url": "wss://api.example/v1/sessions/sess_9f2c.../cdp?token=...",
  "live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=...",
  "token_expires_in_seconds": 1800
}

Limits on the connection

  • At most 10 connections to one session at a time. One more fails the handshake with 429 connection_limit.
  • Text frames only, without WebSocket compression. A binary frame or a message over 16 MiB ends the connection.
  • Three CDP commands are refused, because they would let traffic leave the session around its proxy: Target.createBrowserContext with proxyServer or proxyBypassList, Target.exposeDevToolsProtocol and Target.setRemoteLocations. Each is answered with a CDP error.

What can go wrong

HTTPCodeWhen
403invalid_tokenThe token in cdp_url is bad or expired. The WebSocket handshake fails. Mint a new URL
410session_closedThe session has ended, so there is nothing to connect to
429connection_limitThe session already has 10 CDP connections. The WebSocket handshake fails. Disconnect one first
429concurrency_limitOn create: too many live sessions for this key. Retry-After is set
502session_launch_failedOn create: the browser failed to start
503capacity_unavailableOn create: no browser capacity. Retry-After is set

If a connection drops in the middle of a script, read the session with GET /v1/sessions/{id}: close_reason says whether it reached timeout, sat idle for idle_timeout or the browser exited.

Next

  • Connect: the CDP endpoint and its token.
  • Connect Playwright: the same session from Playwright, in TypeScript or Python.
  • Screenshots: capture a page without a client library.
  • Concepts: when a session ends and how the idle clock works.