Quickstart

Go from an empty project to a cloud browser you drive with Playwright.

1. Install

$
npm install @bctrl/sdk playwright

2. Create a client

1
import { Bctrl } from "@bctrl/sdk";
2
3
const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });

Create an API key in the dashboard. If you omit apiKey, the client reads BCTRL_API_KEY from the environment.

3. Launch a runtime

A runtime is a cloud browser. Create it, then start it to get a connect URL:

1
const runtime = await bctrl.runtimes.create({ type: "browser", name: "quickstart" });
2
const { connectUrl, runId } = await bctrl.runtimes.start(runtime.id);

start mints a fresh, run-scoped connectUrl and opens a run that records everything that happens.

4. Drive it (two options)

1
import { chromium } from "playwright";
2
3
const browser = await chromium.connectOverCDP(connectUrl);
4
const page = browser.contexts()[0]?.pages()[0] ?? (await browser.newPage());
5
6
await page.goto("https://example.com");
7
console.log(await page.title());

Use one controller at a time. See Connect with CDP and Hosted agents for the full surface.

5. Inspect the run

The runId from start lets you read events and open a live view while the browser runs:

1
const run = await bctrl.runs.get(runId);
2
const events = await bctrl.runs.events.list(runId);
3
4
const live = await bctrl.runs.live(runId, { control: "none" });
5
console.log(live.url);

6. Stop the runtime

1
await bctrl.runtimes.stop(runtime.id);

Next

• Spaces - scope what a runtime can access
• Invocations - hosted agent actions
• Runs - events, live view, and recordings