Drive a cloud browser

Start a real Chrome in the cloud, connect your own Playwright to it, and borrow AI only for the steps that are hard to script.

What it does

A session is a stealth Chrome on our fleet with an optional residential proxy, session recording and download capture. You get a connectUrl for Playwright (or any CDP client) and a live viewer link. You stay in control; Copilot helps with one step at a time in English.

Sessions need the cloud browser key (pcb_live_…) from Cloud Platform → APIs & Webhooks → API Keys, because minutes are billed separately; so do the one-shot fetch and search calls. Copilot calls use the platform key.

Three ways to run it

SDK

import { Prompteryx } from '@prompteryx/sdk'
import { chromium } from 'playwright-core'
import { z } from 'zod'
import { docsMetadata } from "@/lib/seo/docs-metadata"

export const metadata = docsMetadata("/docs/developers/browser")

const px = new Prompteryx({
  apiKey: process.env.PROMPTERYX_API_KEY,
  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,
})

const session = await px.cloudBrowser.sessions.create({ recordSession: true, captureDownloads: true })
const browser = await chromium.connectOverCDP(session.connectUrl)
const page = browser.contexts()[0].pages()[0]

await page.goto('https://example.com/signup')
await px.copilot.do(page, 'click the Sign up button')                 // one step in English
await px.copilot.do(page, 'fill the email field with hello@example.com')
const plan = await px.copilot.read(page, z.object({ name: z.string(), pricePerMonth: z.number() }))

await px.cloudBrowser.sessions.close(session.id)

CLI

npx prompteryx login --cloud-browser-key pcb_live_YOUR_KEY
npx prompteryx browser create --record
#   Session pcb_…  (active)
#   Connect with Playwright: chromium.connectOverCDP("wss://…")
#   Watch it live: https://…
npx prompteryx browser close pcb_…

HTTP

curl -X POST https://www.prompteryx.ai/api/v1/cloud-browser/sessions \
  -H "x-api-key: pcb_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"recordSession":true,"captureDownloads":true}'
# → { "id": "pcb_…", "connectUrl": "wss://…", "liveURL": "https://…", "status": "active" }

From an AI assistant (MCP)

"Open https://example.com/pricing in a browser and read me the three plan names."
# Hosted server (Claude, ChatGPT, Cursor…): the assistant calls browser_ai_action, the AI browser agent.
# Local server (npx @prompteryx/mcp-server, PROMPTERYX_EXECUTION_MODE=local + the desktop app):
# 21 step-by-step browser tools (browser_navigate → browser_extract_text …) drive your own Chrome,
# each marked read-only or not so the assistant asks before anything destructive.

Good to know

The details that save a support ticket.

Close sessions when you are done; an idle session still bills minutes until its timeout.

Free accounts get a small monthly minute allowance and can use it here. Recording and residential proxy are paid-plan features.

Prefer your own logged-in Chrome? Install the desktop app and pass target: 'local' (SDK) or --local (CLI). No cloud minutes are used.

Full session, fetch and search reference: Cloud Browser API.