Installation & Setup

View as Markdown

Install

$npm install @bctrl/sdk

Create a client

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

The API key authenticates all requests. Get one from the BCTRL dashboard.

Create a workspace

A workspace is an isolated environment for your agent’s resources. Mount the credentials and storage it needs:

1const workspace = await bctrl.workspaces.create({
2 name: "my-first-workspace",
3 mounts: {
4 ai: { allow: ["openai-prod"] },
5 storage: { workspace: "my-first-workspace" },
6 },
7});

Launch a browser runtime

A runtime is a remote browser running on BCTRL infrastructure. Pick a driver — Playwright, Puppeteer, Stagehand, or Selenium:

1const runtime = await workspace.runtimes
2 .browser("main")
3 .playwright({ mode: "ephemeral" });

Automate

Use the driver’s native API to control the remote browser:

1await runtime.page.goto("https://example.com");
2const title = await runtime.page.title();
3console.log(title);

Clean up

1await runtime.stop();

Full example

1import { Bctrl } from "@bctrl/sdk";
2
3const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });
4
5const workspace = await bctrl.workspaces.create({
6 name: "quickstart",
7});
8
9const runtime = await workspace.runtimes
10 .browser("main")
11 .playwright({ mode: "ephemeral" });
12
13await runtime.page.goto("https://example.com");
14const title = await runtime.page.title();
15console.log(`Page title: ${title}`);
16
17await runtime.stop();

Next steps