Quickstart

GoalProve browser control

Print a session id and title from a managed browser, not local Chrome.

PathRun one narrow lifecycle

Create an API key, start a session, connect Playwright over CDP, then stop it explicitly.

BoundaryRun examples server-side only

Keep keys server-side; never call examples from the frontend.

Prerequisites

You need a Hivebrowser account, a Node.js 20+ server-side runtime, and an API key stored only in server environment variables or a secret manager. Run the examples from a backend, Worker, or job queue, not from frontend code.

1. Get an API Key

Sign up at hivebrowser.ai, then create an API key from the dashboard API Keys page. You will need this key for all API requests.

export HIVEBROWSER_API_KEY="hb_your_api_key_here"

2. Install Dependencies

npm install playwright-core

3. Create a Session and Connect

Create a browser session via the API, then connect to it with Playwright:

import { chromium } from 'playwright-core';

const API = 'https://api.hivebrowser.ai';
const API_KEY = process.env.HIVEBROWSER_API_KEY;

// Create a session
const res = await fetch(`${API}/v1/sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    timeoutSec: 300,
  }),
});

const { data: session } = await res.json();
console.log('Session created:', session.id);

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

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

// Clean up
await browser.close();
await fetch(`${API}/v1/sessions/${session.id}/stop`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
});

If it works, your terminal should print the session id and page title. The browser is running in Hivebrowser's managed environment, not in your local Chrome.

4. Expand the workflow

After the first managed browser session works, add only the capability your workflow needs:

StateReuse a Profile

Persist cookies, localStorage, and browser context when a task should not start from a clean browser.

OutputCapture Artifacts

Store screenshots, PDFs, or extracted content when the run needs durable evidence.

DebugValidate in Playground

Tune selectors, timeouts, recording, and output shape before moving the flow into production code.

Keep the first integration narrow: create a session, connect automation code, stop the session, then add state and artifacts once the runtime path is stable.