Runtimes

A Runtime is the durable resource that performs automation. It represents the thing being automated: a browser today, with computers and spreadsheets as other runtime types in the same model.

A Runtime belongs to a Space and owns its configuration and identity. Tools, Agents, and browser connections all operate through a Runtime.

The API currently exposes one runtime type:

The Runtime response exposes its generated identifier as id (RuntimeId). When another resource or request refers to the Runtime, the field is named runtimeId. Treat the ID as opaque; create it through the API rather than constructing one yourself.

Starting a Runtime opens a Run and returns its runId.

Choose the Runtime lifecycle

The profile option determines whether the browser identity persists:

Use an ephemeral Runtime for isolated jobs. Use a profile-backed Runtime when cookies, logins, or local storage should survive a stop and restart.

Create an ephemeral Runtime

1
const runtime = await bctrl.runtimes.create({
2
  name: "checkout-job",
3
});
4
5
console.log(runtime.id, runtime.activeRunId);
6
console.log(runtime.connection?.cdpUrl);

Ephemeral Runtimes start during creation unless you pass start: false. Their response includes the active Run and run-scoped connection URLs.

If you do not need a label, the minimal request is valid too:

1
const runtime = await bctrl.runtimes.create({});

Create a profile-backed Runtime

Profile-backed Runtimes are reusable and start stopped by default. Pass start: true when you want a one-call create-and-start flow.

1
const runtime = await bctrl.runtimes.create({
2
  name: "customer-portal",
3
  profile: true,
4
});
5
6
const started = await bctrl.runtimes.start(runtime.id);
7
console.log(started.runId, started.connection.cdpUrl);
8
9
await bctrl.runtimes.stop(runtime.id);
10
11
// Start the same Runtime later. Its browser identity is retained.
12
await bctrl.runtimes.start(runtime.id);

Runtime ID and Run ID

Use the Runtime object’s id when operating on the Runtime. Use the Run’s runId when inspecting one execution:

Runtime lifecycle

The Runtime owns the lifecycle; each start opens a Run:

1
const current = await bctrl.runtimes.get(runtime.id);
2
const runtimes = await bctrl.runtimes.list({ spaceId: "default" });
3
4
await bctrl.runtimes.update(runtime.id, {
5
  name: "customer-portal-prod",
6
});
7
8
await bctrl.runtimes.stop(runtime.id);

Runtime status is active, stopped, or failed. Read the associated Run to understand what happened during an active or completed session.

Configure the browser

Runtime creation has two kinds of options:

• Lifecycle options decide where the Runtime belongs, whether its browser identity persists, and when it starts.
• Browser configuration decides how the browser behaves once it starts.

Creation parameters

Browser configuration parameters

Pass browser-specific settings in config:

1
const runtime = await bctrl.runtimes.create({
2
  name: "research-session",
3
  config: {
4
    headless: true,
5
    stealth: "best",
6
    proxy: "proxy_123",
7
    extensionIds: ["ext_123"],
8
    idleTimeoutSeconds: 900,
9
    webRtcProxyOnly: true,
10
    networkTraffic: {
11
      saver: "medium",
12
      blockAds: true,
13
    },
14
  },
15
});

Network traffic parameters

1
type BrowserRuntimeCreateConfig = {
2
  autoUpgrade?: boolean;
3
  extensionIds?: string[];
4
  fingerprint?: {
5
    browser?: "chrome";
6
    viewport?: {
7
      height: number;
8
      width: number;
9
    };
10
  };
11
  forceOpenShadowRoots?: boolean;
12
  headless?: boolean;
13
  idleTimeoutSeconds?: number;
14
  networkTraffic?: BrowserNetworkTrafficConfig;
15
  proxy?: RuntimeProxyInput;
16
  stealth?: "normal" | "best" | "experimental";
17
  webRtcProxyOnly?: boolean;
18
};

Profile-backed Runtimes retain browser identity. Keep their configuration focused on settings that should apply to every start:

1
const runtime = await bctrl.runtimes.create({
2
  profile: true,
3
  name: "customer-portal",
4
  config: {
5
    proxy: "proxy_123",
6
    idleTimeoutSeconds: 900,
7
  },
8
});

Use the Stealth browsing cookbook, Load browser extensions cookbook, and Trim network traffic cookbook for complete recipes. This page is the option map; the cookbooks show the combinations.

Next

• Runs — understand the session opened by a Runtime
• Connect with CDP — attach Playwright or Puppeteer
• Connect with WebDriver — attach Selenium