> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Runtimes

> Create, configure, start, and stop managed cloud browsers.

A **runtime** is a managed cloud browser running on BCTRL infrastructure. Create it with a configuration, start it to get a connect URL, drive it, then stop it. Browser is the only runtime type today.

## Create a runtime

```ts
const runtime = await bctrl.runtimes.create({
  type: "browser",
  name: "main",
});
```

Scope it to a [space](/sdk/spaces) with `spaceId` so it inherits that space's storage, vault, and AI mounts:

```ts
const runtime = await bctrl.runtimes.create({
  spaceId: space.id,
  type: "browser",
  name: "main",
});
```

## Configure the browser

Pass `config` to set stealth, proxy, fingerprint, extensions, and network behaviour:

```ts
const runtime = await bctrl.runtimes.create({
  type: "browser",
  name: "stealthy",
  config: {
    stealth: "high",
    proxy: { mode: "saved", id: "pxy_123" },
    fingerprint: { browser: "chrome", locale: "en-US" },
    extensionIds: ["ext_123"],
    idleTimeoutMinutes: 10,
  },
});
```

See [Runtime configuration](/sdk/runtime-config) for the full set of options, and [Proxies](/sdk/proxies) and [Extensions](/sdk/extensions) for the resources they reference.

## Start a runtime

Starting boots the browser and mints a fresh, run-scoped connect URL:

```ts
const { connectUrl, runId, runtimeId } = await bctrl.runtimes.start(runtime.id);
```

Every start opens a new [run](/sdk/runs) (`runId`) where the session is recorded. The `connectUrl` is a credentialed CDP endpoint - see [Connect with CDP](/sdk/connect-cdp).

`start` accepts an idempotency key so retries do not double-start:

```ts
await bctrl.runtimes.start(runtime.id, { idempotencyKey: "boot-2024-06-01" });
```

## List, read, and stop

`list` returns every runtime in the organization; pass `spaceId` to narrow to one space.

```ts
const { data } = await bctrl.runtimes.list({ spaceId: space.id });

for await (const rt of bctrl.runtimes.iter()) {
  console.log(rt.id, rt.status);
}

const current = await bctrl.runtimes.get(runtime.id);

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

## Update and delete

`name` and `idleTimeoutMinutes` are editable any time; `config` only while the runtime is stopped. The name is a display label - renaming never affects the runtime's browser state.

```ts
await bctrl.runtimes.update(runtime.id, { name: "renamed", idleTimeoutMinutes: 15 });

await bctrl.runtimes.delete(runtime.id);
```

Deleting requires the runtime to be stopped; pass `{ force: true }` to stop and delete in one call.

## Targets (tabs)

A running browser exposes its pages as **targets**. List them, open new ones, switch focus, and close them:

```ts
const { data: targets } = await bctrl.runtimes.targets.list(runtime.id);

const tab = await bctrl.runtimes.targets.create(runtime.id, {
  uri: "https://example.com",
  activate: true,
});

await bctrl.runtimes.targets.activate(runtime.id, tab.id);

await bctrl.runtimes.targets.delete(runtime.id, tab.id);
```

Hosted [invocations](/sdk/invocations) act on the active target by default, so `activate` is how you point an agent at a specific tab.

## Files on a runtime

Move files in and out of a running browser. These operate on the live runtime filesystem, distinct from the durable run artifacts in [Run files](/sdk/run-files):

```ts
await bctrl.runtimes.files.list(runtime.id);

await bctrl.runtimes.files.upload(runtime.id, {
  file: new Blob(["name,email\n..."]),
  runtimePath: "/work/input.csv",
});

await bctrl.runtimes.files.stage(runtime.id, {
  fileId: "file_123",
  runtimePath: "/work/input.csv",
});

await bctrl.runtimes.files.collect(runtime.id, {
  runtimePath: "/work/output.pdf",
});
```

`stage` copies a durable file into the runtime; `collect` saves a runtime file back to durable storage.

## Next

* [Connect with CDP](/sdk/connect-cdp) - drive the runtime yourself
* [Invocations](/sdk/invocations) - hand it to a hosted agent
* [Runtime configuration](/sdk/runtime-config) - stealth, proxy, fingerprint