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

# Bring your own driver

> Connect Playwright or Puppeteer to a Gravix browser over a tokened CDP bridge

Drive a Gravix browser from your own tooling — Playwright, Puppeteer, or anything that speaks the Chrome DevTools Protocol. `cdp_endpoint` opens a tokened bridge into the running browser: connect with the returned URL and your driver sees a normal Chromium.

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

## Connect Playwright

The response carries `port`, `path`, and `token` (minted when you don't supply
one). The bridge is reachable through the runtime's service-port host —
`wss://{port}-{runtime_id}.service.gravixlayer.ai{path}?token={token}` — the same
convention as [live view](https://docs.gravixlayer.ai/documentation/agentruntime/browser-use/capture.md). Each
bridge accepts multiple concurrent driver connections; `cdp_endpoint_stop` tears
it down.

```python Python theme={null}
from gravixlayer import GravixLayer
from playwright.sync_api import sync_playwright

client = GravixLayer()  # reads GRAVIXLAYER_API_KEY
sandbox = client.runtime.create(template="browser-small")
bid = sandbox.browser.open(url="https://example.com")["browser_id"]

ep = sandbox.browser.cdp_endpoint(bid)
# Service-port convention: wss://{port}-{runtime_id}.service.gravixlayer.ai
ws = f"wss://{ep['port']}-{sandbox.runtime_id}.service.gravixlayer.ai{ep['path']}?token={ep['token']}"

with sync_playwright() as p:
    browser = p.chromium.connect(ws)
    page = browser.contexts[0].pages[0]
    print(page.title())
    browser.close()  # closes the driver session, not the Gravix browser

sandbox.browser.cdp_endpoint_stop(bid)
sandbox.kill()
```

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

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

const ep = await sandbox.browser.cdpEndpoint(bid);
// Service-port convention: wss://{port}-{runtime_id}.service.gravixlayer.ai
const ws = `wss://${ep.port}-${sandbox.runtimeId}.service.gravixlayer.ai${ep.path}?token=${ep.token}`;

const browser = await chromium.connect(ws);
const page = browser.contexts()[0]?.pages()[0];
console.log(await page?.title());
await browser.close(); // closes the driver session, not the Gravix browser

await sandbox.browser.cdpEndpointStop(bid);
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime browser cdp-endpoint "$RT" --browser b1 --output json
# → {"port": 9223, "path": "/cdp", "token": "…"}
# Connect: wss://9223-$RT.service.gravixlayer.ai/cdp?token=…

gravixlayer runtime browser cdp-endpoint-stop "$RT" --browser b1
```

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

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

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

> [!WARNING]
>
> Closing the *driver's* connection leaves the Gravix browser running — that is what makes mixed control (SDK + your driver on the same session) work. Driver-level `Browser.close` calls are rejected so a stray client cannot kill the shared session. Use `cdp_endpoint_stop` to retire the bridge, and `browser.close` to close the browser itself.


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