> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Load an extension

> Install an unpacked extension into a running browser

Load an unpacked extension into a running browser — ad blockers, automation helpers, in-house tooling — without rebuilding the runtime image. The extension directory must live in the runtime's workspace (put it there with `runtime.files` or `runtime.exec`).

CLI and cURL examples use `$RT` and browser `b1` ([Sessions](https://docs.gravixlayer.ai/documentation/agentruntime/browser-use/browser.md)).

## Load and unload

`extension_load` takes a workspace path containing a `manifest.json` and
returns `{extension_id}` — keep it for `extension_unload`. Extensions survive
navigations and new tabs in the same browser.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()  # reads GRAVIXLAYER_API_KEY
sandbox = client.runtime.create(template="browser-small")
bid = sandbox.browser.open()["browser_id"]

# Ship the extension directory into the runtime, then load it
r = sandbox.browser.extension_load(bid, "/workspace/extensions/umatrix")
ext_id = r["extension_id"]

sandbox.browser.goto("https://example.com")  # extension is active
sandbox.browser.extension_unload(bid, ext_id)
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'browser-small' });
const bid = (await sandbox.browser.open()).browserId;

const r = await sandbox.browser.extensionLoad(bid, '/workspace/extensions/umatrix');

await sandbox.browser.goto('https://example.com'); // extension is active
await sandbox.browser.extensionUnload(bid, r.extension_id);
await sandbox.kill();
```

```bash CLI theme={null}
EXT_ID=$(gravixlayer runtime browser extension-load "$RT" --browser b1 \
  /workspace/extensions/umatrix --output json | jq -r .extension_id)

gravixlayer runtime browser extension-unload "$RT" --browser b1 "$EXT_ID"
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/extensions/load" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/extensions/umatrix"}'

curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/extensions/unload" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"extension_id": "x1"}'
```

> [!NOTE]
>
> Extension loading works on the pipe transport that runs every Gravix browser — a capability that is unavailable over the usual WebSocket debugging channel. It requires a headed or `headless=new` browser, which is what `browser.open` always starts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.