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

# Connections

> Short-lived protocol leases for controlling a runtime with external automation tools.

A connection is a temporary lease into a running runtime. It gives your code a protocol endpoint, such as a CDP WebSocket, without exposing host internals or long-lived credentials.

Use connections when your own process controls the browser. Use invocations when BCTRL should run hosted AI work inside the runtime.

Only one controller can own a browser runtime at a time. Creating a connection while an invocation is active, or creating an invocation while a connection lease is active, returns `runtime.controller_busy`.

## Create a connection

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

const wsUrl = connection.endpoint.url;
```

The returned URL is shown once. Store the connection ID if you need to list or delete the lease later.

```ts
await runtime.connections.delete(connection.id);
```

## Connect with Playwright

```ts
import { chromium } from "playwright";

const connection = await runtime.connections.create({ protocol: "cdp" });
const browser = await chromium.connectOverCDP(connection.endpoint.url);

const context = browser.contexts()[0] ?? await browser.newContext();
const page = context.pages()[0] ?? await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());
```

## Connection lifecycle

Connections are short-lived by design.

| Step             | What happens                                                                        |
| ---------------- | ----------------------------------------------------------------------------------- |
| Create           | BCTRL returns a signed endpoint for one protocol.                                   |
| Use              | Your native framework connects directly to the runtime.                             |
| Observe          | The run records events, commands, artifacts, live view, and recording metadata.     |
| Expire or delete | The endpoint stops accepting new attaches and releases the runtime controller lock. |

## Related

* [Connect with CDP](/sdk/browser-runtimes)
* [Runtimes](/sdk/core-concepts/runtimes)
* [Runs](/sdk/core-concepts/runs)