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

# Browser extensions

> Store reusable CRX packages and load them into browser Runtimes.

A **Browser extension** is a reusable Chromium `.crx` package stored by BCTRL.
Import an extension from a Chrome Web Store detail URL or upload a CRX package,
then reference its ID in browser Runtime configuration.

## Import an extension

Import from a Chrome Web Store detail URL:

```ts
const extension = await bctrl.browserExtensions.import({
  url: "https://chromewebstore.google.com/detail/example/extension-id",
  name: "Checkout helper",
});

console.log(extension.id, extension.name, extension.version);
```

Or upload a CRX package directly:

```ts
const extension = await bctrl.browserExtensions.upload({
  file: new Blob([crxBytes], { type: "application/x-chrome-extension" }),
  name: "Checkout helper",
});
```

The upload `name` is optional. When omitted, BCTRL uses the extension manifest
name.

## Load an extension in a Runtime

Pass stored extension IDs in the browser Runtime configuration:

```ts
const runtime = await bctrl.runtimes.create({
  config: {
    extensionIds: [extension.id],
  },
});
```

Extensions are loaded when the browser starts. To change the extension list on
a profile-backed Runtime, update its configuration while it is stopped, then
start it again:

```ts
await bctrl.runtimes.update(runtime.id, {
  config: {
    extensionIds: [extension.id],
  },
});

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

See [Runtimes](/sdk/runtimes) for the complete browser configuration shape.

## List extensions

```ts
for await (const item of bctrl.browserExtensions.iter({
  source: "url",
})) {
  console.log(item.id, item.name, item.version, item.profileCount);
}
```

Available filters are:

| Filter   | Type                | Description                         |
| -------- | ------------------- | ----------------------------------- |
| `q`      | `string`            | Search extension metadata           |
| `format` | `"crx"`             | Filter by package format            |
| `source` | `"upload" \| "url"` | Filter by how the package was added |

`list()` returns one cursor page. `iter()` follows all pages automatically.

## Rename and delete

```ts
const current = await bctrl.browserExtensions.get(extension.id);

await bctrl.browserExtensions.update(extension.id, {
  name: "Checkout automation helper",
});

await bctrl.browserExtensions.delete(extension.id);
```

Delete an extension when it should no longer be available to new Runtime
starts. Remove it from Runtime configuration first; deletion can be rejected
while the extension is still in use.

## Extension fields

| Field                     | Type     | Always present | Description                                         |
| ------------------------- | -------- | -------------- | --------------------------------------------------- |
| `id`                      | `string` | Yes            | Extension identifier used in Runtime configuration. |
| `name`                    | `string` | Yes            | Display name.                                       |
| `version`                 | `string` | Yes            | Version from the extension package.                 |
| `format`                  | `"crx"`  | Yes            | Package format currently supported.                 |
| `sourceUrl`               | `string` | No             | Original import URL, when imported from a URL.      |
| `sizeBytes`               | `number` | No             | Package size, when available.                       |
| `contentHash`             | `string` | No             | SHA-256 package hash, when available.               |
| `profileCount`            | `number` | Yes            | Number of browser profiles using the extension.     |
| `subaccountId`            | `string` | No             | Subaccount owner, when applicable.                  |
| `createdAt` / `updatedAt` | `string` | Yes            | Timestamps.                                         |