Skip to main content
Every browser automation starts with a browser. You launch a cloud Chromium instance, get a Playwright context, and write your automation against it. Cookies, localStorage, and auth state persist across every page you open inside that browser. This page covers browser lifecycle for code-based automations using the Skyvern SDK. If you’re running automations through the Cloud UI workflow editor, browser management is handled automatically. See Browser Sessions for the Cloud UI equivalent.

​
Launch a cloud browser

browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
ParameterTypeDefaultDescription
timeoutintNoneSession timeout in minutes (5-1440). Server default: 60 minutes
proxy_locationProxyLocationNoneRoute traffic through a geographic proxy
The browser stays alive until timeout expires or you call browser.close(). After a successful launch the handle exposes:
  • browser.browser_session_id: the pbs_* session id, useful for locking tasks to this session or for logging
  • browser.pages: the list of open Playwright pages in this browser context
If timeout < 5, Skyvern rejects the request with UnprocessableEntityError (422). An invalid proxy_location enum is rejected the same way. 
# Launch with a 2-hour timeout and US residential proxy
browser = await skyvern.launch_cloud_browser(
    timeout=120,
    proxy_location="RESIDENTIAL"
)

​
Reuse an existing browser

If you have a cloud browser session already running, reuse it instead of launching a new one. 
# Reuse the most recent available session, or create one if none exists
browser = await skyvern.use_cloud_browser()

# Connect to a specific session by ID
browser = await skyvern.connect_to_cloud_browser_session("pbs_abc123")
use_cloud_browser checks for an available session first. If one exists, it connects to it. If not, it creates a new one with the options you provide. Passing an unknown session id to connect_to_cloud_browser_session raises NotFoundError (HTTP 404).

​
Connect to a local browser

Connect to any browser running with Chrome DevTools Protocol (CDP) enabled. This works with local Chrome, Chromium, or any CDP-compatible browser. 
browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
page = await browser.get_working_page()
Start Chrome with CDP enabled: 
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222
For self-hosted Skyvern deployments, you can also launch a local Chromium browser directly (Python only): 
# Requires Skyvern.local() - not available in cloud mode
skyvern = Skyvern.local()
browser = await skyvern.launch_local_browser(headless=False, port=9222)
See the Self-Hosted Browser Configuration guide for headless/headful modes, display settings, and Docker setups.

​
Working with pages

​
Get the current page

page = await browser.get_working_page()
Returns the most recent page. If no pages are open, creates a new one. Each call returns a fresh SkyvernBrowserPage wrapper. Don’t rely on identity (is / ===) comparisons between the return value and earlier page references.

​
Open a new tab

page2 = await browser.new_page()
await page2.goto("https://example.com/other-page")
Both pages share the same browser context (cookies, auth state).

​
Wrap an existing Playwright page (Python only)

skyvern_page = await browser.get_page_for(existing_playwright_page)
Adds AI methods to a Playwright page you already have.

​
Close the browser

await browser.close()
Closes the browser and releases cloud resources. If connected to a cloud session, the session ends. Any unsaved state (cookies, localStorage) is lost unless you saved a browser profile first.

​
Proxy and geolocation

Route browser traffic through residential proxies in specific countries. 
browser = await skyvern.launch_cloud_browser(
    proxy_location="RESIDENTIAL"
)
Available locations:
ValueRegion
RESIDENTIALUnited States (default)
RESIDENTIAL_GBUnited Kingdom
RESIDENTIAL_DEGermany
RESIDENTIAL_ESSpain
RESIDENTIAL_FRFrance
RESIDENTIAL_IEIreland
RESIDENTIAL_INIndia
RESIDENTIAL_JPJapan
RESIDENTIAL_AUAustralia
RESIDENTIAL_CACanada
NONENo proxy (direct connection)
For self-hosted proxy configuration, see Proxy Setup.

​
Session persistence

Two mechanisms for preserving browser state between automation runs: Browser Sessions keep a browser alive between API calls. Use create_browser_session from the Tasks API to create a session, then pass its ID to multiple run_task calls. See Browser Sessions. Browser Profiles save a snapshot of browser state (cookies, localStorage) that persists indefinitely. Create a profile from a completed run, then load it into future runs to skip login. See Browser Profiles.

​
Full reference