SandboxesBrowser Sandbox

Browser Sandbox Endpoints

Browser Sandbox

Create and manage remote Browser Sandbox sessions. Connect with Playwright or Puppeteer via WebSocket for full browser automation, or view the browser live via VNC.

Remote Browser Control

Each session launches an isolated browser instance. Connect via WebSocket to automate with Playwright/Puppeteer, or use the live view URL to watch the browser in real time.

POST/v1/browser-sandbox/session

Create a new Browser Sandbox session for remote control. Returns a WebSocket URL to connect with Playwright/Puppeteer.

Request Body

Parameter	Type	Description
`width`	number	Browser viewport width (800-3840). Defaults to 1280
`height`	number	Browser viewport height (600-2160). Defaults to 720
`headless`	boolean	Run browser in headless mode. Defaults to true
`browser`	"camoufox" \| "lightpanda"	Browser engine. camoufox: full Firefox with VNC support. lightpanda: lightweight CDP headless. Defaults to camoufox
`proxy`	boolean	Use proxy for the browser. Defaults to true

Example Request

cURL

Node.js

curl -X POST https://api.builde2e.com/api/v1/browser-sandbox/session \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer uc-YOUR-API-KEY' \
  -d '{
    "browser": "camoufox",
    "headless": true,
    "ttlSeconds": 300
  }'

Example Response

json

{
  "sessionId": "sess_abc123",
  "wsUrl": "wss://api.builde2e.com/browser-sandbox-ws?sessionId=sess_abc123",
  "liveViewUrl": "wss://api.builde2e.com/vnc-ws?sessionId=sess_abc123",
  "browser": "camoufox",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "width": 1280,
  "height": 720,
  "costPerMin": 0.01
}

Response Fields

Field	Type	Description
`sessionId`	string	Unique session identifier
`wsUrl`	string	WebSocket URL for connecting with Playwright/Puppeteer
`liveViewUrl`	string \| null	Live view URL for watching the browser in real time (null if headless or lightpanda)
`browser`	string	Browser engine used (camoufox or lightpanda)
`createdAt`	string	ISO timestamp when session was created
`width`	number	Browser viewport width
`height`	number	Browser viewport height
`costPerMin`	number	Cost per minute in USD. Headless: $0.002/min. Visible: $0.01/min

GET/v1/browser-sandbox/session/:id

Get details about a Browser Sandbox session including its status, cost, and timestamps.

Example Request

cURL

curl https://api.builde2e.com/api/v1/browser-sandbox/session/SESSION_ID \
  -H 'Authorization: Bearer uc-YOUR-API-KEY'

Example Response

json

{
  "sessionId": "sess_abc123",
  "status": "active",
  "width": 1280,
  "height": 720,
  "headless": false,
  "proxy": true,
  "browser": "camoufox",
  "wsUrl": "wss://api.builde2e.com/browser-sandbox-ws?sessionId=sess_abc123",
  "liveViewUrl": "wss://api.builde2e.com/vnc-ws?sessionId=sess_abc123",
  "totalCost": 0.02,
  "hasStorageState": true,
  "lastUrl": "https://example.com/dashboard",
  "closeReason": null,
  "closedAt": null,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "lastActivityAt": "2025-01-15T10:35:00.000Z"
}

Response Fields

Field	Type	Description
`sessionId`	string	Unique session identifier
`status`	string	Session status (active, closed)
`width`	number	Browser viewport width
`height`	number	Browser viewport height
`headless`	boolean	Whether the session is headless
`proxy`	boolean	Whether the session uses a proxy
`browser`	string	Browser engine used (camoufox or lightpanda)
`wsUrl`	string	WebSocket URL
`liveViewUrl`	string \| null	Live view URL (null if headless)
`totalCost`	number	Total accumulated cost in USD
`hasStorageState`	boolean	Whether the session has saved browser state for resuming
`lastUrl`	string \| null	Last URL visited in the session
`closeReason`	string \| null	Reason the session was closed (manual, timeout, error)
`closedAt`	string \| null	ISO timestamp when the session was closed
`createdAt`	string	ISO timestamp when session was created
`lastActivityAt`	string	ISO timestamp of last activity

DELETE/v1/browser-sandbox/session/:id

Close a Browser Sandbox session. The browser state (cookies, localStorage) is automatically saved for later resumption.

Example Request

cURL

curl -X DELETE https://api.builde2e.com/api/v1/browser-sandbox/session/SESSION_ID \
  -H 'Authorization: Bearer uc-YOUR-API-KEY'

Example Response

json

{
  "success": true,
  "sessionId": "sess_abc123"
}

POST/v1/browser-sandbox/session/:id/resume

Resume a previously closed Browser Sandbox session. A new browser instance is launched with the saved state (cookies, localStorage) restored.

Example Request

cURL

Node.js

curl -X POST https://api.builde2e.com/api/v1/browser-sandbox/session/SESSION_ID/resume \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer uc-YOUR-API-KEY' \
  -d '{
    "ttlSeconds": 300
  }'

Example Response

json

{
  "sessionId": "sess_abc123",
  "wsUrl": "wss://api.builde2e.com/browser-sandbox-ws?sessionId=sess_abc123",
  "liveViewUrl": "wss://api.builde2e.com/vnc-ws?sessionId=sess_abc123",
  "browser": "camoufox",
  "createdAt": "2025-01-15T11:00:00.000Z",
  "width": 1280,
  "height": 720,
  "costPerMin": 0.01
}

The response format is identical to the create endpoint. The session ID remains the same, and you get a fresh WebSocket URL to connect to.

GET/v1/browser-sandbox/sessions

List all active browser sessions on this pod. No authentication required.

Example Response

json

[
  {
    "sessionId": "session-1-1709553600000",
    "wsUrl": "ws://...",
    "liveViewUrl": null,
    "createdAt": "2026-03-04T12:00:00.000Z",
    "lastActivityAt": "2026-03-04T12:05:30.000Z",
    "ageMinutes": 5.5
  }
]

WebSocket Endpoints

Browser Control

Path: /browser-sandbox-ws?sessionId={sessionId}

Transparent bidirectional WebSocket proxy between your client and the browser. Connect with Playwright:

javascript

const browser = await chromium.connectOverCDP(session.wsEndpoint);

VNC Live View

Path: /vnc-ws?sessionId={sessionId}

VNC proxy for live browser viewing. Use with react-vnc or any VNC WebSocket client. The VNC pipeline starts on-demand when the first client connects and stops when the last client disconnects. Only available for non-headless Camoufox sessions.

Using the SDK

The Node.js SDK provides a simple interface for Browser Sandbox session management:

javascript

import BuildE2E from '@builde2e/sdk';
import { chromium } from 'playwright-core';

BuildE2E.setApiKey('uc-YOUR-API-KEY');

// Create a session
const session = await BuildE2E.browser.create({
  width: 1280,
  height: 720,
  headless: false
});

// Connect with Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');

// Check session details
const details = await BuildE2E.browser.get(session.sessionId);
console.log(details.status);    // "active"
console.log(details.totalCost); // 0.02 (visible) or 0.004 (headless)

// Close the session (state is saved)
await BuildE2E.browser.close(session.sessionId);

// Resume later with saved cookies/localStorage
const resumed = await BuildE2E.browser.resume(session.sessionId);
const browser2 = await chromium.connectOverCDP(resumed.wsEndpoint);

Playwright Example — SDK Only

The Node.js SDK makes it easy to create a session and connect via Playwright:

Node.js

import { chromium } from 'playwright';

const session = await BuildE2E.browser.create({
  browser: 'camoufox',
  headless: true
});

// Connect via Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto('https://example.com');
const title = await page.title();
console.log(title);

// Clean up
await browser.close();
await BuildE2E.browser.close(session.sessionId);

Pricing

Browser Sandbox sessions are billed per minute. Visible sessions (headless: false) cost $$0.01 USD/min (~$$0.60/hour). Headless sessions cost $$0.002 USD/min (~$$0.12/hour). Billing starts when the session is created and stops when it is closed or times out.