Quickstart | BCTRL Docs

Install the SDK and set your API key:

pnpm add @bctrl/sdk

export BCTRL_API_KEY=your_api_key

Create a runtime

An ephemeral browser runtime starts immediately by default. Its response includes the active Run that was opened for the session.

import { Bctrl } from "@bctrl/sdk";
const bctrl = new Bctrl({
  apiKey: process.env.BCTRL_API_KEY,
});
const runtime = await bctrl.runtimes.create({
  name: "quickstart",
});
const runId = runtime.activeRunId;
if (!runId) {
  throw new Error("The runtime did not start");
}

This uses the platform defaults: the caller’s default Space, a browser Runtime, recording enabled, and an ephemeral Runtime that starts immediately. The name is optional; when omitted, BCTRL uses the Runtime ID as the name.

Run a tool

Tools that may take longer than one request are started as durable ToolCalls. Wait for the result with the ToolCall client:

const call = await bctrl.tools.start("browser.pages.open", {
  url: "https://example.com",
}, { runtimeId: runtime.id });
const page = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 30,
});
console.log(page);

The same Run contains the runtime lifecycle and the ToolCall. Read it when you need the final status or identifiers for later inspection:

const run = await bctrl.runs.get(runId);
console.log(run.status, run.runtimeId);

Stop the runtime when the work is complete:

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

Create a runtime

Run a tool

What to read next