Core Concepts

Connections

View as Markdown

A connection is a temporary lease into a running runtime. It gives your code a protocol endpoint, such as a CDP WebSocket, without exposing host internals or long-lived credentials.

Use connections when your own process controls the browser. Use invocations when BCTRL should run hosted AI work inside the runtime.

Create a connection

1const connection = await runtime.connections.create({
2  protocol: "cdp",
3});
4
5const wsUrl = connection.endpoint.url;

The returned URL is shown once. Store the connection ID if you need to list or delete the lease later.

1await runtime.connections.delete(connection.id);

Connect with Playwright

1import { chromium } from "playwright";
2
3const connection = await runtime.connections.create({ protocol: "cdp" });
4const browser = await chromium.connectOverCDP(connection.endpoint.url);
5
6const context = browser.contexts()[0] ?? await browser.newContext();
7const page = context.pages()[0] ?? await context.newPage();
8
9await page.goto("https://example.com");
10console.log(await page.title());

Connection lifecycle

Connections are short-lived by design.

StepWhat happens
CreateBCTRL returns a signed endpoint for one protocol.
UseYour native framework connects directly to the runtime.
ObserveThe run records events, commands, artifacts, live view, and recording metadata.
Expire or deleteThe endpoint stops accepting new attaches.