Automate the hard parts

Persistent Sessions

View as Markdown

A profile-backed runtime keeps its browser state across starts: cookies, logins, local storage - and the fingerprint identity, which matters just as much. A site that sees the same session cookie arrive from a brand-new fingerprint every day has a reason to challenge you.

1import { Bctrl } from "@bctrl/sdk";
2
3const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });
4
5const runtime = await bctrl.runtimes.create({
6  type: "browser",
7  name: "acme-session",
8  config: { profile: true, idleTimeoutMinutes: 15 },
9});
10
11// First start: log in once.
12const first = await bctrl.runtimes.start(runtime.id);
13
14// Easiest way to seed the session: a human does the login through
15// a takeover link - no credentials in code at all.
16const live = await bctrl.runs.live(first.runId, {
17  control: "input",
18  expiresInSeconds: 600,
19});
20console.log("Open this and log in:", live.url);
21
22// ...once the login is done:
23await bctrl.runtimes.stop(runtime.id);
24
25// Any later start resumes the same browser. Hours or days later:
26const later = await bctrl.runtimes.start(runtime.id);
27// -> already logged in; connect over CDP or run invocations as usual.

🎬 Content TODO: a two-part GIF sells this instantly - left: human logs into a site through the takeover link; right: a restart minutes later landing straight on the logged-in dashboard.

Scripted logins work too - use vault credentials on the first start instead of a takeover link.

What persists, what doesn’t

The runtime itself is the long-term browser: its state lives and dies with it. Stop and restart the same runtime to resume; creating a new runtime always starts fresh. Stealth, fingerprint, and extensions are managed by the platform for the life of the profile, so the identity stays coherent across restarts - you can still change proxy, idleTimeoutMinutes, and network settings between starts.

Ephemeral runtimes (profile unset) discard everything on stop. Use them for one-shot jobs; use profile-backed runtimes for anything that returns to the same site as the same user.

Next