Skip to main content
Sessions are isolated browser instances running in the cloud that you can control programmatically. Each session gives you a WebSocket endpoint to connect with Playwright, Puppeteer, or any CDP-compatible tool.

​
Quick Start

Create a session with default settings: 
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const session = await client.sessions.create();

  console.log("Session ID:", session.id);
  console.log("WebSocket:", session.wsEndpoint);
  console.log("Live Url:", session.liveUrl);
}

main();
You can view the live session at the live url link provided in the response. Active sessions can be also viewed and managed in the Sessions page in the dashboard.
Remember to stop the sessions when are you are done with them. See the Session Lifecycle guide for more information on managing sessions through code.

​
Configuration Options

Customize your session with these options: 
const session = await client.sessions.create({
  acceptCookies: true,
  useStealth: true,
  useUltraStealth: false,
  useProxy: true,
  screen: {
    width: 1920,
    height: 1080,
  },
  timeoutMinutes: 30,
});

​
Common Configuration Options

​
acceptCookies
boolean
default:false
Automatically accept cookies on pages that are visited in the session
​
useStealth
boolean
default:false
Enable standard stealth mode to evade basic bot detection
​
useUltraStealth
boolean
default:false
Enable advanced stealth mode for maximum bot detection evasion (reach out to us at info@hyperbrowser.ai to get access)
​
useProxy
boolean
default:false
Route traffic through a proxy (see Proxy Guide for configuration)
​
screen
object
Screen dimensions with width and height (default: 1280x720)
​
timeoutMinutes
number
Session timeout in minutes (min: 1, max: 720)
This shows the most commonly used options. For the complete list of configuration parameters including proxy settings, CAPTCHA solving, recordings, profiles, extensions, and more, see:

​
Session Response

The API returns a session object with these properties: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sessionUrl": "https://...",
  "wsEndpoint": "wss://...",
  "liveUrl": "https://...",
  "computerActionEndpoint": "https://...",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  ... // other properties
}
To see the complete list of properties, see the API Reference.
​
id
string
Unique session identifier
​
wsEndpoint
string
WebSocket URL for browser automation
​
liveUrl
string
URL to view the session in real-time
​
sessionUrl
string
URL to view the session page in the dashboard
​
computerActionEndpoint
string
URL to send computer actions to the session
​
status
string
Current status (active, closed, or error)
​
createdAt
string
ISO 8601 timestamp

​
Stealth Mode

Bypass bot detection with stealth features: 
// Standard stealth (recommended for most sites)
const session = await client.sessions.create({
  useStealth: true,
});

// Ultra stealth (for challenging sites)
const session = await client.sessions.create({
  useUltraStealth: true,
});
Ultra stealth is only available on enterprise plans. Reach out to us at info@hyperbrowser.ai to learn more.

​
Proxies

Route sessions through proxies for geo-targeting or additional anonymity: 
const session = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
});
See the Proxy Guide for advanced proxy configuration including states, cities, and custom proxy servers.

​
Session Timeout

Sessions automatically close after a certain amount of time based on your team’s default timeout setting. You can change the default timeout on the Settings page. You can also configure the timeout per session during session creation: 
const session = await client.sessions.create({
  timeoutMinutes: 60, // 1 hour
});

​
Custom Screen Size

Set custom screen dimensions for specific testing scenarios: 
const session = await client.sessions.create({
  screen: {
    width: 1920,
    height: 1080,
  },
});

​
Next Steps

Lifecycle Management

Stop, monitor, and manage active sessions

Connect with Playwright

Use Playwright to control your session

Connect with Puppeteer

Use Puppeteer to control your session

Stealth Mode

Deep dive into anti-detection features