# Browser Sessions

Browser sessions give you a real Chromium instance inside a dedicated microVM, exposed through a standard Chrome DevTools Protocol (CDP) endpoint. The browser is a genuine desktop Chrome installation -- not headless-only, not a container-shared process.

## Create a browser session

<CodeBlocks>
```bash title="CLI"
# Ephemeral
chaser browser --ephemeral --json

# Persistent (workspace-backed)
chaser workspaces create --session-type browser --name my-browser --json
chaser browser --workspace my-browser --json
```

```bash title="REST API"
# Ephemeral
curl -sS "$CHASER_API_URL/v1/sessions" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_type": "browser", "ephemeral": true}' | jq

# Persistent
curl -sS "$CHASER_API_URL/v1/sessions" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_type": "browser", "workspace": "my-browser"}' | jq
```

```bash title="MCP"
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {"ephemeral": true, "action": "prepare"}
    }
  }' | jq
```
</CodeBlocks>

## Connect with Playwright

```typescript
import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("https://<session_id>.chaser.sh/");
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();
```

## Connect with Puppeteer

```typescript
import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://<session_id>.chaser.sh/"
});
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
```

## CDP discovery endpoints

The session control URL supports standard CDP discovery routes:

- `GET /json/version` -- browser version and WebSocket debugger URL
- `GET /json/list` -- open tabs/targets
- `GET /json/protocol` -- full CDP protocol definition

## MCP browser tool

The `browser` MCP tool provides three actions:

| Action | Description |
|--------|-------------|
| `prepare` | Returns session details, CDP endpoint, and an MCP `server_config` for the attached `chrome-devtools-mcp` bridge |
| `discover` | Lists available browser automation tools from `chrome-devtools-mcp` |
| `call` | Executes a specific browser tool with `method` and `params` |

```bash
# Discover available browser tools
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {"session_id": "<session_id>", "action": "discover"}
    }
  }' | jq
```

## Browser jobs

For queued browser work instead of direct CDP control, use the jobs API:

- `browser.action` -- sequential CDP method calls
- `browser.scrape` -- navigate to a URL and optionally extract content by selector

```bash
chaser jobs scrape <session_id> --url "https://example.com" --wait --json
```

See [Jobs](/docs/platform/jobs) for details.

## Proxy selection

Browser sessions accept an optional `proxy` selector to route traffic through residential or datacenter proxies. If omitted, the platform applies a default based on your billing plan.

## Stealth

Chaser browser sessions are designed to present as real desktop Chrome installations. Each session runs a genuine Chromium binary inside its own VM with a real display server, real system fonts, and standard browser fingerprints. The CDP proxy layer applies additional hardening to prevent common automation detection signals.

Stealth outcomes depend on your target sites and traffic patterns. Test against your specific targets for best results.