SDK Overview

View as Markdown

BCTRL gives automation agents managed browser runtimes they can control from your code. The SDK handles spaces, runtime lifecycle, connection leases, hosted invocations, storage, and run observability.

The browser itself is still controlled by the tools you already use.

Runtime = control
Run = observability

Use runtime APIs to launch, connect, invoke, move files, and stop. Use run APIs to inspect events, commands, artifacts, live view, and recordings.

Canonical browser flow

1import { Bctrl } from "@bctrl/sdk";
2import { chromium } from "playwright";
3
4const bctrl = new Bctrl({
5  apiKey: process.env.BCTRL_API_KEY!,
6});
7
8const space = await bctrl.spaces.create({
9  name: "browser-agent",
10});
11
12const runtime = await space.runtimes.browser.launch({
13  name: "main",
14});
15
16const connection = await runtime.connections.create({
17  protocol: "cdp",
18});
19
20const browser = await chromium.connectOverCDP(connection.endpoint.url);
21const page = browser.contexts()[0]?.pages()[0] ?? await browser.newPage();
22
23await page.goto("https://example.com");
24
25const run = await runtime.currentRun();
26
27await run.events.list();
28await run.artifacts.list();
29
30await runtime.stop();

Core resources

ResourcePurpose
SpacesTask and permission boundaries for runtimes, storage, vault access, AI credentials, and tools.
RuntimesLive execution targets. Browser runtimes are the stable runtime type today.
ConnectionsShort-lived protocol leases for external tools such as Playwright, Puppeteer, or debuggers.
InvocationsHosted AI work that BCTRL runs inside a runtime, such as Stagehand or browser-use tasks.
RunsDurable records for events, commands, artifacts, live view, recordings, and activity.

Connections vs invocations

Use connections when your own process controls the browser through CDP.

Use invocations when BCTRL should run hosted AI work inside the runtime.