Driving a Browser

Runtime configuration

View as Markdown

Pass a config object to create a runtime and control how the browser presents itself and what it can reach.

1const runtime = await bctrl.runtimes.create({
2  type: "browser",
3  name: "stealthy",
4  config: {
5    stealth: "high",
6    proxy: { mode: "saved", id: "pxy_123" },
7    fingerprint: { browser: "chrome", locale: "en-US" },
8    extensionIds: ["ext_123"],
9    idleTimeoutMinutes: 10,
10    webRtcProxyOnly: true,
11    networkTraffic: { blockAds: true, blockTrackers: true },
12  },
13});

Options

OptionPurpose
stealthAnti-detection hardening: "medium", "high", or "ultra".
proxyA proxy: { mode: "saved", id }, or inline { mode: "custom", protocol, host, port }.
fingerprintThe fingerprint the browser presents: { browser, locale }.
extensionIdsBrowser extensions to load at launch.
idleTimeoutMinutesAuto-stop the runtime after this much inactivity.
autoUpgradeUpgrade the browser to the latest version on each start (default true). The fingerprint keeps its identity; only the browser version advances. Set false to pin.
webRtcProxyOnlyForce WebRTC through the proxy to avoid IP leaks.
forceOpenShadowRootsOpen closed shadow roots for automation.
networkTrafficFilter network traffic: blockAds, blockTrackers, and urlAllowlist / urlBlocklist.

Profile-backed runtimes

A runtime is either ephemeral (browser state is discarded on stop) or profile-backed (cookies, logins, and local storage persist across starts). Set config.profile: true to make it profile-backed - the runtime itself is the long-term browser, and its state lives and dies with it. Stop and restart the same runtime to resume where it left off; creating a new runtime always starts fresh.

Profile-backed runtimes accept autoUpgrade, idleTimeoutMinutes, webRtcProxyOnly, forceOpenShadowRoots, and networkTraffic. Stealth, proxy, fingerprint, and extensions are managed by the platform for the life of the profile.

1const runtime = await bctrl.runtimes.create({
2  type: "browser",
3  name: "acme-session", // a display label - renaming never affects browser state
4  config: { profile: true, idleTimeoutMinutes: 15 },
5});

Next