Skip to main content

View on GitHub

View on NPM

​
Installation

Install the Hyperbrowser SDK via npm or yarn: 
npm install @hyperbrowser/sdk dotenv

​
Quick Start

Initialize the client with your API key: 
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

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

​
Configuration Options

interface HyperbrowserConfig {
  apiKey?: string; // API key (can also use HYPERBROWSER_API_KEY env var)
  baseUrl?: string; // Base API URL (default: "https://api.hyperbrowser.ai")
  timeout?: number; // Request timeout in milliseconds (default: 30000)
}

​
TypeScript Support

The SDK is fully typed with TypeScript. Import types from @hyperbrowser/sdk/types: 
import {
  SessionDetail,
  CreateSessionParams,
  CreateSandboxParams,
  ScrapeJobResponse,
  CrawlJobResponse,
  ExtractJobResponse,
  BrowserUseTaskResponse,
  // ... and many more
} from "@hyperbrowser/sdk/types";

​
Sandboxes

The Node SDK also includes the sandbox runtime for processes, files, terminal sessions, snapshots, and exposed ports: 
const sandbox = await client.sandboxes.create({
  imageName: "node",
});

const result = await sandbox.exec("node -v");
console.log(result.stdout.trim());

await sandbox.stop();
Sandbox guides:

​
Integration Examples

import { chromium } from "playwright-core";
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({
    acceptCookies: true,
  });

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);
    const defaultContext = browser.contexts()[0];
    const page = defaultContext.pages()[0];

    await page.goto("https://example.com");
    console.log(await page.title());
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
}

main().catch(console.error);

​
Computer Actions

Programmatically control the browser with low-level actions. For the session-id parameter, you can also just pass in the detailed session object itself, and it is actually recommended to do so.

​
Click

const response = await client.computerAction.click(
  "session-id",  // or session object
  500,  // x coordinate
  300,  // y coordinate
  "left",  // button: "left" | "right" | "middle" | "back" | "forward" | "wheel"
  1,  // number of clicks
  false  // do not return screenshot (default: false)
);

console.log(response.success);
console.log(response.screenshot);  // base64 if requested

​
Type Text

const response = await client.computerAction.typeText(
  "session-id",
  "Hello, World!",
  false  // do not return screenshot (default: false)
);

​
Press Keys

Uses the xdotool format for keys: https://github.com/sickcodes/xdotool-gui/blob/master/key_list.csv 
const response = await client.computerAction.pressKeys(
  "session-id",
  ["Control_L", "a"],  // Key combination
  false  // do not return screenshot (default: false)
);

​
Move Mouse

const response = await client.computerAction.moveMouse(
  "session-id",
  500,  // x
  300,  // y
  false  // do not return screenshot (default: false)
);

​
Drag

const response = await client.computerAction.drag(
  "session-id",
  [
    { x: 100, y: 100 },
    { x: 200, y: 200 },
    { x: 300, y: 300 },
  ],
  false  // do not return screenshot (default: false)
);

​
Scroll

const response = await client.computerAction.scroll(
  "session-id",
  500,  // x position
  300,  // y position
  0,  // scroll x delta
  100,  // scroll y delta
  false  // do not return screenshot (default: false)
);

​
Screenshot

const response = await client.computerAction.screenshot("session-id");
console.log(response.screenshot);  // base64

​
Support