Getting Started with Cloud Browser
Cloud Browser provides remote browser sessions accessible via WebSocket using the Chrome DevTools Protocol (CDP). Connect with Puppeteer, Playwright, Selenium, or AI agent frameworks like Browser Use, Stagehand, and Vibium.
Key Features
Remote Browser Sessions
Access real Chrome browsers running in the cloud via CDP WebSocket connections
Proxy Integration
Choose between datacenter or residential proxy networks for geo-targeting
OS Fingerprinting
Emulate Windows, macOS, or Linux browser environments
Session Persistence
Maintain browser state across multiple connections with session resume
Human-in-the-Loop
Take manual control of sessions for debugging and CAPTCHA solving
Debug Mode
Record sessions as videos for debugging and analysis
WebSocket Connection
Connect to Cloud Browser using a CDP-compatible WebSocket URL with your API key and optional parameters:
Connection Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
api_key |
Yes | - | Your Scrapfly API key for authentication |
proxy_pool |
No | datacenter |
Proxy network type: datacenter or residential |
os |
No | random | Operating system fingerprint: linux, windows, or macos |
browser_brand |
No | chrome |
Chromium-based browser brand used for fingerprint generation. Valid values:
chrome, edge, brave, opera.
Invalid values are silently dropped and the default applies.
|
session |
No | - | Optional session identifier for maintaining browser state across connections. See Session Resume. |
country |
No | - | Proxy country code (ISO 3166-1 alpha-2), e.g., us, uk, de |
auto_close |
No | true |
Automatically stop the browser session when the CDP connection disconnects. Set to false to keep the browser alive for reconnection. |
timeout |
No | 900 |
Maximum session duration in seconds (15 minutes default, 30 minutes max). |
debug |
No | false |
Enable session recording for debugging. See Debug Mode. |
block_images |
No | false |
Stub image requests with a transparent 1x1 pixel. Reduces bandwidth while remaining invisible to anti-bot systems. |
block_styles |
No | false |
Stub stylesheet requests with an empty CSS response. |
block_fonts |
No | false |
Stub font requests with an empty response. |
block_media |
No | false |
Stub video and audio media requests. |
blacklist |
No | false |
Stub known analytics, tracking, and telemetry URLs. |
cache |
No | false |
Enable HTTP cache for static resources. Cached bandwidth billed at 1 credit/MB. |
No-Effect CDP Commands
Cloud Browser automatically manages browser fingerprinting, emulation, and device metrics to provide optimal anti-detection and consistency. As a result, the following CDP commands are silently ignored when sent through the WebSocket connection:
os, country, etc.).
| CDP Command | Description |
|---|---|
Emulation.setDeviceMetricsOverride |
Device screen dimensions, pixel ratio, and mobile emulation |
Emulation.setUserAgentOverride |
User-Agent string, platform, and client hints |
Emulation.setTimezoneOverride |
Browser timezone |
Emulation.setLocaleOverride |
Browser locale and language settings |
Emulation.setHardwareConcurrencyOverride |
Number of CPU cores reported by navigator.hardwareConcurrency |
Emulation.setVisibleSize |
Visible viewport size |
Emulation.setEmulatedMedia |
Media type and feature overrides (e.g. prefers-color-scheme) |
Emulation.setDefaultBackgroundColorOverride |
Default background color override |
Emulation.setNavigatorOverrides |
Navigator platform override |
Emulation.setPageScaleFactor |
Page zoom/scale factor |
If you need to control any of these settings, use the
connection parameters instead (e.g. os for OS fingerprinting, country for locale/timezone).
Integrations
Cloud Browser uses the standard Chrome DevTools Protocol (CDP), making it compatible with all major browser automation tools and AI agent frameworks.
Quick Start Examples
Connect to Cloud Browser using your preferred automation tool:
Billing
Cloud Browser uses a billing model based on session time, bandwidth, and optional cached bandwidth:
- All proxy types 1 credit
- Datacenter 7 credits
- Residential 52 credits
- All proxy types 1 credit
Troubleshooting
Cause: Invalid API key or network connectivity issues.
Solution:
- Verify your API key is correct
- Ensure your firewall allows WebSocket connections
- Check if you're behind a corporate proxy that blocks WebSocket
Cause: Session ID not provided or session expired.
Solution: Always include the same session parameter in the WebSocket URL for persistent sessions.
Note: Sessions expire after 1 hour of inactivity by default.
Cause: Browser session timeout or crash.
Solution:
- Always call
browser.close()to properly terminate sessions - Implement reconnection logic in your automation
- Monitor your scripts for memory leaks or infinite loops
Related Documentation
- Session Resume - Reconnect to existing browser sessions
- Human-in-the-Loop - Take manual control of sessions for debugging
- Debug Mode - Record sessions as videos for analysis
- File Downloads - Retrieve downloaded files from browser sessions
- Cloud Browser Billing - Detailed pricing and cost calculation
- Puppeteer Integration - Full Puppeteer setup guide
- Playwright Integration - Full Playwright setup guide
- Browser Use Integration - AI agent framework setup
- Stagehand Integration - AI-powered browser automation setup
- No-Effect CDP Commands - CDP commands silently ignored by Cloud Browser
- Error Reference - All Cloud Browser API errors and troubleshooting
- General Billing Overview - Account-wide billing information