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.
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:
Example DomainKeep 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()andbrowser.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_founduntilPOST /v1/sessions/{id}/tabsopens 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.
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{
"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.createBrowserContextwithproxyServerorproxyBypassList,Target.exposeDevToolsProtocolandTarget.setRemoteLocations. Each is answered with a CDP error.
What can go wrong
| HTTP | Code | When |
|---|---|---|
| 403 | invalid_token | The token in cdp_url is bad or expired. The WebSocket handshake fails. Mint a new URL |
| 410 | session_closed | The session has ended, so there is nothing to connect to |
| 429 | connection_limit | The session already has 10 CDP connections. The WebSocket handshake fails. Disconnect one first |
| 429 | concurrency_limit | On create: too many live sessions for this key. Retry-After is set |
| 502 | session_launch_failed | On create: the browser failed to start |
| 503 | capacity_unavailable | On 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.