> 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.

# SDK Overview

> Managed browser runtimes, CDP connections, hosted invocations, and run observability.

BCTRL gives automation agents managed browser runtimes they can control from your code. The SDK handles spaces, runtime lifecycle, connection leases, hosted invocations, storage, and run observability.

The browser itself is still controlled by the tools you already use.

```txt
Runtime = control
Run = observability
```

Use runtime APIs to launch, connect, invoke, move files, and stop. Use run APIs to inspect events, commands, artifacts, live view, and recordings.

Browser runtimes have a strict controller lock. Use either a CDP connection from your own process or a hosted invocation from BCTRL, but not both at the same time on the same runtime.

## Canonical browser flow

```ts
import { Bctrl } from "@bctrl/sdk";
import { chromium } from "playwright";

const bctrl = new Bctrl({
  apiKey: process.env.BCTRL_API_KEY!,
});

const space = await bctrl.spaces.create({
  name: "browser-agent",
});

const runtime = await space.runtimes.browser.launch({
  name: "main",
});

const connection = await runtime.connections.create({
  protocol: "cdp",
});

const browser = await chromium.connectOverCDP(connection.endpoint.url);
const page = browser.contexts()[0]?.pages()[0] ?? await browser.newPage();

await page.goto("https://example.com");

const run = await runtime.currentRun();

await run.events.list();
await run.artifacts.list();

await runtime.stop();
```

## Core resources

| Resource    | Purpose                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------- |
| Spaces      | Task and permission boundaries for runtimes, storage, vault access, AI credentials, and tools. |
| Runtimes    | Live execution targets. Browser runtimes are the stable runtime type today.                    |
| Connections | Short-lived protocol leases for external tools such as Playwright, Puppeteer, or debuggers.    |
| Invocations | Hosted AI work that BCTRL runs inside a runtime, such as Stagehand or browser-use tasks.       |
| Runs        | Durable records for events, commands, artifacts, live view, recordings, and activity.          |

## Connections vs invocations

Use **connections** when your own process controls the browser through CDP.

Use **invocations** when BCTRL should run hosted AI work inside the runtime.

Both target the same live runtime. If one controller is active, the other returns `runtime.controller_busy` until the connection is revoked, expires, or the invocation reaches a terminal state.

## What to read next

* [Installation & Setup](/sdk/getting-started)
* [Browser Quickstart](/sdk/getting-started/browser-quickstart)
* [Connections](/sdk/core-concepts/connections)
* [Runs](/sdk/core-concepts/runs)