This guide shows how to open a Wayfern browser session, drive it with Playwright or Puppeteer, and close it. It also shows what a session costs.

Get a link token

A session opens on a browser link. A link belongs to a project and holds a token. Create a link in the dashboard on the project page. Project owners and admins can see the token. Members cannot.

A link token is not a wf_ API token. It only opens browser sessions. The connection URL is:

wss://api.wayfern.com/ws?token=$WAYFERN_LINK_TOKEN

There is no REST call that creates a session. When you open the WebSocket, the session starts.

Connect with Playwright

import { chromium } from "playwright";

const url = `wss://api.wayfern.com/ws?token=${process.env.WAYFERN_LINK_TOKEN}`;

// A cold start takes about 45 to 50 seconds. Playwright waits 30 s by default.
const browser = await chromium.connectOverCDP(url, { timeout: 120_000 });
try {
  // The browser's own context has the device, the window size and the exit.
  const context = browser.contexts()[0];
  const page = await context.newPage();
  await page.goto("https://example.com");
  console.log(await page.title());
  await page.close();
} finally {
  await browser.close();
}

Use browser.contexts()[0]. A context that you create with browser.newContext() gets its own device and is not sized to the link’s viewport.

Connect with Puppeteer

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://api.wayfern.com/ws?token=${process.env.WAYFERN_LINK_TOKEN}`,
  // Keep the real window size instead of an 800 x 600 emulation.
  defaultViewport: null,
});
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await page.close();
await browser.disconnect();

End a Puppeteer session with browser.disconnect(). browser.close() sends Browser.close, which stops the browser process. Connections of the same link that are open at the same time can run in one browser.

What happens when you connect

The gateway checks the token, the connection cap of the link and your balance. Then it starts a browser or reuses one, and sends a connected message before the CDP stream starts. The gateway holds up to 4 MiB of commands that you send before the browser is ready.

If the gateway refuses the connection, it closes the socket with a code:

Code	Meaning
4001	No token in the URL
4002	Token is invalid, revoked or expired
4003	The link has its maximum number of open connections
4005	Billing gate: no plan or packs, or too few credits
4402	Sent during a session: the balance can no longer pay

The full list is in the Browser API reference.

Close the session

When the WebSocket closes, the session ends. The gateway bills the time each open page has not paid yet and stops the meter. When the last connection on a browser closes, Wayfern stops that browser.

A session has no maximum length and no idle timeout. An open page runs, and bills, until you close it or your balance runs out. Close pages that you do not need, and disconnect when the job ends.

What a session costs

Billing is per open page, not per connection.

Browser time is 8 credits per open page per hour, metered per second. At the list rate of $0.0125 a credit, that is $0.10 an hour.
Each page bills at least 60 seconds. A page open for 5 seconds bills 60 seconds (0.133 credits). A page open for 95 seconds bills 95 seconds.
To connect, your account needs a plan or credit packs, and credits for 60 seconds of browser time.
The gateway debits every 30 seconds. If a debit fails, it sends a CDP error and closes the socket with 4402.
The default datacenter exit is free. Residential bandwidth is 320 credits per GB.

Open pages count toward the concurrency cap of your plan, across all your connections: 20 on Developer and on packs only, 100 on Business, 400 on Scale. Past the cap, the command that opens a page fails with CDP error -32000. The pages that you have keep running. A link also caps its connections, from 1 to 100 (default 10).

See usage rates and browser limits.