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

# Setting up a Chrome extension Surface

Use a Chrome extension [Surface](/user-guide/products-surfaces/what-are-surfaces) to package your [Product](/user-guide/products-surfaces/what-are-products)'s AI as a downloadable Manifest V3 extension. Your users chat with your AI in the browser side panel. The extension can provide packaged browser tools for reading pages, filling forms, and navigating tabs. Build the extension ZIP from the Surface's **Ship** tab.

## Before you begin

Create a Product and attach at least one Capability. Use a Flow or Agent that handles user messages as the Capability. For instructions, see [Adding Capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product).

The Chrome extension Surface is behind a gradual rollout. If **Chrome Extension** does not appear in the Surface type list, the Surface is not available for your account.

## Create the Chrome extension Surface

Create the Surface from the **Product** that you want to ship:

1. Open the **Product** you want to ship as an extension.
2. Open **Surfaces** and click **Add Surface**.
3. Select **Chrome Extension** as the Surface type.
4. Optional: rename the Surface. Runtype names it **Chrome Extension** followed by a short ID.
5. Click **Save**.
6. Connect your Capability to the Surface. For instructions, see [Connect a Capability to a Surface](/user-guide/products-surfaces/adding-capabilities-to-a-product#connect-a-capability-to-a-surface).

The extension download fails until at least one Capability is connected to the Surface.

## Configure the extension

Use the Surface configuration panel to set the extension's name, behavior, and tools. The panel includes these fields:

* **Extension name**: appears in the Chrome toolbar and extension manager. It defaults to the Surface name.
* **Extension description**: appears in the extension manager and, if you publish the extension, in the Chrome Web Store listing.
* **Chat location**: controls where the chat opens. We recommend **Side panel** because it stays open while your users browse. **Toolbar popup** closes when it loses focus, which stops in-progress runs. Use it for quick, one-shot questions.
* **Browser tools**: define the tool categories available to your AI.
* **Optional host permissions**: accept match patterns, one per line. For example, `https://*.example.com/*`. Your users can grant these permissions at runtime for matching sites. Otherwise, the extension accesses only the tab where the user opens it.
* **First-run consent screen**: defaults to on. It shows a disclosure before page content is sent to your AI. Keep it on if you plan to publish the extension. For more information, see [Distribute through the Chrome Web Store](#distribute-through-the-chrome-web-store).
* **Input placeholder**: sets the placeholder text in the chat input.

## Choose browser tools

Browser tools are fixed handlers that the extension packages. The extension passes parameters, such as a CSS selector, a value, or a URL. It does not pass code. Tools that make changes, such as clicking, navigating, copying to the clipboard, or showing a notification, ask the user for confirmation in the chat before they run. Read-only tools run automatically.

Enable only the categories that your use case needs. The available categories are:

| Category             | What your AI can do                                                  | Notes                                                                       |
| -------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Page reading**     | Read page text, HTML, your selection, and metadata; take screenshots | Read-only tools run automatically                                           |
| **Page interaction** | Find and read elements, click elements, read or fill forms           | Actions that change the page ask for confirmation                           |
| **Tab navigation**   | List, open, close, and navigate tabs                                 | Adds the `tabs` permission, which Chrome labels as reading browsing history |
| **Clipboard**        | Read or copy clipboard text                                          | Adds the `clipboardRead` and `clipboardWrite` permissions                   |
| **Notifications**    | Show Chrome desktop notifications                                    | Adds the `notifications` permission                                         |

The extension always requests `storage`. Side-panel mode also requests `sidePanel`. When you enable **Page reading**, **Page interaction**, or **Clipboard**, the extension adds `activeTab` and `scripting`. These permissions grant temporary access to the tab where the user opens the extension. They don't create install warnings. Tab navigation adds the `tabs` permission. Optional host permissions add access to matching sites after the user grants them at runtime.

If you select no browser tool categories, the extension remains chat-only.

## Download the extension

Open the Surface's **Ship** tab and click **Download extension ZIP** to build the bundle. The first download also configures the resources that the bundle needs:

* **A pinned extension ID**: the bundle includes a manifest `key`. Every unpacked install then uses the same extension ID and `chrome-extension://` origin. The ID appears in the **Ship** tab and the configuration panel.
* **A client token scoped to the Surface's Capabilities**: the download adds the extension's origin to the token's allowed origins. Runtype reuses a matching token for this Surface or creates one. For more information, see [Client tokens and domain restrictions](/user-guide/products-surfaces/client-tokens-and-domain-restrictions).
* **Browser tool access for the extension**: Runtype lets your AI use the extension's browser tools when requests come from the extension's origin.

Repeat downloads keep the same extension ID, so you can rebuild the bundle after configuration changes without breaking installed copies. After you change the configuration, download the ZIP again, replace the unzipped folder, and click the reload button on the extension in `chrome://extensions`.

## Install the extension for testing

To test the extension, follow these steps:

1. Unzip the downloaded ZIP.
2. Open `chrome://extensions`.
3. Turn on **Developer mode**.
4. Click **Load unpacked** and select the unzipped folder.
5. Open the extension from the Chrome toolbar.

Chrome 134 and later disables unpacked extensions when **Developer mode** is off. Treat an unpacked installation as a testing channel. To distribute the extension to end users, publish it through the Chrome Web Store.

## Distribute through the Chrome Web Store

The generated bundle includes a README with the publishing checklist. Complete these requirements before you publish:

1. **Host a privacy policy** that names Runtype and its model providers as data recipients. Link it in the Chrome Web Store developer dashboard.
2. **Complete the privacy practices form**. In the **Privacy practices** tab, provide a single-purpose description, a reason for every permission, the data-usage certifications, and the Limited Use certification.
3. **Keep the first-run consent screen enabled**. Chrome Web Store policy requires prominent disclosure and affirmative consent when page content goes to an AI backend.
4. **Remove the `key` field from `manifest.json` for the first upload of a new store item**. Chrome rejects bundles that include this field. It assigns the store item its own extension ID. After publishing, add the store-assigned ID's `chrome-extension://` origin to the client token's allowed origins. Also allow browser tools from that origin, as described in [Allow browser tools for a store build](#allow-browser-tools-for-a-store-build).
5. **Prefer unlisted distribution** for white-label or business-to-business deployments.

Plan for manual review. Reviews for new developer accounts can take days to weeks.

### Allow browser tools for a store build

Your AI can use browser tools only when requests come from an origin that the Surface allows. The download allows only the pinned extension ID's origin, and the dashboard has no control to add another. If you skip this step, chat works in the store build but the AI can't use browser tools.

To allow the store build, update the Surface with the Runtype API. The following request allows browser tools from both extension origins:

```bash
curl -X PUT "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "behavior": {
      "type": "chrome_extension",
      "webmcp": {
        "enabled": true,
        "allowlist": [
          { "origin": "chrome-extension://YOUR_PINNED_EXTENSION_ID", "tools": ["browser_*"] },
          { "origin": "chrome-extension://YOUR_STORE_EXTENSION_ID", "tools": ["browser_*"] }
        ]
      }
    }
  }'
```

Replace the following:

* `YOUR_API_KEY`: your Runtype API key. For more information, see [Authentication](/developer-guides/getting-started/authentication).
* `YOUR_PRODUCT_ID` and `YOUR_SURFACE_ID`: the IDs of your Product and Chrome extension Surface.
* `YOUR_PINNED_EXTENSION_ID`: the extension ID that the **Ship** tab shows. Keep this rule so that unpacked test installs still work.
* `YOUR_STORE_EXTENSION_ID`: the ID that the Chrome Web Store assigned.

The request replaces the whole `webmcp` setting, so include every origin that you want to keep. To confirm the change, ask the published extension to read the current page and check that the tool runs.

## Next steps

Follow these guides to continue:

* [What are Surfaces?](/user-guide/products-surfaces/what-are-surfaces): understand how Surfaces expose a Product
* [Adding Capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product): attach a Flow or Agent
* [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes): route requests across multiple Capabilities
* [Client tokens and domain restrictions](/user-guide/products-surfaces/client-tokens-and-domain-restrictions): manage allowed origins for the client token
* [Working with logs](/user-guide/logs/working-with-logs): inspect requests and tool activity