> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Quickstart

> Create a browser runtime, run a tool, and inspect the resulting Run.

Install the SDK and set your API key:

```bash
pnpm add @bctrl/sdk
```

```bash
export BCTRL_API_KEY=your_api_key
```

## Create a runtime

An ephemeral browser runtime starts immediately by default. Its response includes
the active Run that was opened for the session.

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

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

const runtime = await bctrl.runtimes.create({
  name: "quickstart",
});

const runId = runtime.activeRunId;
if (!runId) {
  throw new Error("The runtime did not start");
}
```

This uses the platform defaults: the caller’s default Space, a browser Runtime,
recording enabled, and an ephemeral Runtime that starts immediately. The name
is optional; when omitted, BCTRL uses the Runtime ID as the name.

## Run a tool

Tools that may take longer than one request are started as durable ToolCalls.
Wait for the result with the ToolCall client:

```ts
const call = await bctrl.tools.start("browser.pages.open", {
  url: "https://example.com",
}, { runtimeId: runtime.id });

const page = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 30,
});

console.log(page);
```

The same Run contains the runtime lifecycle and the ToolCall. Read it when you
need the final status or identifiers for later inspection:

```ts
const run = await bctrl.runs.get(runId);
console.log(run.status, run.runtimeId);
```

Stop the runtime when the work is complete:

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

## What to read next

* [Core model](/sdk/core-model) - how Spaces, Runtimes, Runs, and automation fit together
* [Spaces](/sdk/spaces) - scope storage, Vault access, and AI credentials
* [Runtimes](/sdk/runtimes) - choose ephemeral or profile-backed browser state
* [Runs](/sdk/runs#trace-and-events) - inspect and stream Run activity