---
name: browser
description: Use Dench Browser from sandbox Playwright scripts without provider credentials.
---

# Dench Browser Playwright CDP

Use this reference when writing durable website automation scripts in a Dench
sandbox.

For short interactive diagnosis, use the chat `browser` tool. For larger or
repeatable workflows, write a file-backed Playwright script in `/workspace` and
connect it to a Dench Browser CDP session.

## Requirements

The sandbox already provides:

- `DENCH_API_KEY` for the Dench gateway
- `DENCH_GATEWAY_URL` for gateway routing
- `DENCH_RUN_ID` so session metadata can attach to the chat run
- `PLAYWRIGHT_CORE_PATH` so scripts can import Playwright without installing it

Your persisted login profile is resolved server-side per signed-in user from the
Dench API key — there is no browser context id to pass and no
`DENCH_BROWSER_CONTEXT_ID` env var. Do not look for browser provider API keys in
the sandbox.

## Create A Session

```bash
dench browser session create --json
```

The response includes:

- `sessionId`
- `connectUrl`
- `liveViewUrl`
- `status`
- optional `contextId`

The CLI best-effort registers the session for the current `DENCH_RUN_ID`, so the
chat Browser panel can show the live session and replay.

## Connect With Playwright

```js
import { pathToFileURL } from "node:url";
import { promisify } from "node:util";
import { execFile } from "node:child_process";

const execFileAsync = promisify(execFile);

const { chromium } = await import(
  pathToFileURL(process.env.PLAYWRIGHT_CORE_PATH).href
);

const { stdout } = await execFileAsync("dench", [
  "browser",
  "session",
  "create",
  "--json",
]);
const session = JSON.parse(stdout);
const browser = await chromium.connectOverCDP(session.connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
```

Close the Playwright connection when the script ends. Stop the Dench Browser
session unless the user needs to finish login in the live Browser panel:

```bash
dench browser session stop "$SESSION_ID" --json
```

## Repair Checklist

If a script cannot start:

```bash
node -e 'console.log(JSON.stringify({ hasDenchApiKey: Boolean(process.env.DENCH_API_KEY), hasPlaywrightCorePath: Boolean(process.env.PLAYWRIGHT_CORE_PATH) }))'
```

If a fresh session still looks logged out after the user completed login, the
saved profile catches up automatically on the next session — just create a new
session and retry.