Usage

Environment setup

Store your API key in a .env file at the project root:

HYPERBROWSER_API_KEY=your_key_here

---

Minimal session example (Node.js)

Creates a cloud browser session, takes a screenshot, and stops the session.

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 response = await client.computerAction.screenshot(session.id);
    console.log(response.screenshot);
  } finally {
    await client.sessions.stop(session.id);
  }
}

main().catch(console.error);

---

Minimal session example (Python)

from hyperbrowser import Hyperbrowser
from dotenv import load_dotenv
import os

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

session = client.sessions.create()
print(session.ws_endpoint)

client.sessions.stop(session.id)

---

AI agent task (Browser-Use) -- Node.js

Runs a natural-language browser task using the Browser-Use agent backed by Hyperbrowser's cloud browser.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

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

async function main() {
  const result = await client.agents.browserUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    llm: "gemini-2.5-flash",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});

---

AI agent task (Browser-Use) -- Python

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartBrowserUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.browser_use.start_and_wait(
    params=StartBrowserUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post",
        llm="gemini-2.5-flash",
        max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")

---

Playwright with Hyperbrowser (Node.js)

Swap the local browser launch for a Hyperbrowser cloud session WebSocket endpoint.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { connect } from "playwright-core";
import { config } from "dotenv";

config();

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

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

  const browser = await connect(session.ws_endpoint);
  const page = await browser.newPage();

  await page.goto("https://example.com");
  console.log(await page.title());

  await browser.close();
  await client.sessions.stop(session.id);
}

main().catch(console.error);

---

Key session response fields

Field	Description
session.id	Unique session identifier
session.ws_endpoint	WebSocket URL for Playwright/Puppeteer/Selenium
session.live_url	Live viewer URL at app.hyperbrowser.ai
session.status	Current session status

More examples

• Examples repo: https://github.com/hyperbrowserai/examples
• App examples (full web apps): https://github.com/hyperbrowserai/hyperbrowser-app-examples
• Interactive playground: https://app.hyperbrowser.ai/playground