> ## Documentation Index
> Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Browsers

> Launch or connect to a browser and get pages to automate.

Browser automation drives a Playwright browser with AI added on top. Start from a `Skyvern` client, get a `SkyvernBrowser`, then a page.

## Launch or connect

### skyvern.launch\_cloud\_browser

Launch a new cloud-hosted browser session.

This creates a new browser session in Skyvern's cloud infrastructure and connects to it.

```python Python theme={null}
await skyvern.launch_cloud_browser(
    *,
    timeout: int | None = None,
    proxy_location: ProxyLocationInput = None,
    extensions: list[Extensions] | None = None,
    browser_profile_id: str | None = None,
    browser_type: PersistentBrowserType | None = None,
) -> SkyvernBrowser
```

```typescript TypeScript theme={null}
skyvern.launchCloudBrowser(options?: { timeout?: number; proxyLocation?: ProxyLocation; }): Promise<SkyvernBrowser>
```

**Parameters**

**timeout** `int | None`

Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60.

Default: `None`

**proxy\_location** `ProxyLocationInput`

Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

Default: `None` · TypeScript: `proxyLocation`

**extensions** `list[Extensions] | None`

Browser extensions to install in the session.

Default: `None` · Python only

**browser\_profile\_id** `str | None`

Browser profile ID to load into the session.

Default: `None` · Python only

**browser\_type** `PersistentBrowserType | None`

Browser engine for the session (msedge, chrome, or stealth-chromium).

Default: `None` · Python only

**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the new cloud session.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.launch_cloud_browser()
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.launchCloudBrowser();
console.log(result);
```

***

### skyvern.use\_cloud\_browser

Get or create a cloud browser session.

This method attempts to reuse the most recent available cloud browser session.
If no session exists, it creates a new one. This is useful for cost efficiency
and session persistence.

```python Python theme={null}
await skyvern.use_cloud_browser(
    *,
    timeout: int | None = None,
    proxy_location: ProxyLocationInput = None,
) -> SkyvernBrowser
```

```typescript TypeScript theme={null}
skyvern.useCloudBrowser(options?: { timeout?: number; proxyLocation?: ProxyLocation; }): Promise<SkyvernBrowser>
```

**Parameters**

**timeout** `int | None`

Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60. Only used when creating a new session.

Default: `None`

**proxy\_location** `ProxyLocationInput`

Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Only used when creating a new session.

Default: `None` · TypeScript: `proxyLocation`

**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to an existing or new cloud session.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.use_cloud_browser()
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.useCloudBrowser();
console.log(result);
```

***

### skyvern.connect\_to\_cloud\_browser\_session

Connect to an existing cloud-hosted browser session by ID.

```python Python theme={null}
await skyvern.connect_to_cloud_browser_session(
    browser_session_id: str,
) -> SkyvernBrowser
```

```typescript TypeScript theme={null}
skyvern.connectToCloudBrowserSession(browserSessionId: string): Promise<SkyvernBrowser>
```

**Parameters**

**browser\_session\_id** `str` *required*

The ID of the cloud browser session to connect to.

TypeScript: `browserSessionId`

**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the cloud session.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.connect_to_cloud_browser_session(browser_session_id="pbs_123")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.connectToCloudBrowserSession("pbs_123");
console.log(result);
```

***

### skyvern.connect\_to\_browser\_over\_cdp

Connect to an existing browser instance via Chrome DevTools Protocol (CDP).

Use this to connect to a browser that's already running with CDP enabled,
whether local or remote.

```python Python theme={null}
await skyvern.connect_to_browser_over_cdp(cdp_url: str) -> SkyvernBrowser
```

```typescript TypeScript theme={null}
skyvern.connectToBrowserOverCdp(cdpUrl: string): Promise<SkyvernBrowser>
```

**Parameters**

**cdp\_url** `str` *required*

The CDP WebSocket URL (e.g., "[http://localhost:9222](http://localhost:9222)").

TypeScript: `cdpUrl`

**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the existing browser.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.connect_to_browser_over_cdp(cdp_url="http://localhost:9222")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
console.log(result);
```

***

### skyvern.launch\_local\_browser

Launch a new local Chromium browser with Chrome DevTools Protocol (CDP) enabled.

This method launches a browser on your local machine with remote debugging enabled,
allowing Skyvern to control it via CDP. Useful for development and debugging.

> [!NOTE]
>
> Python only: the TypeScript SDK has no equivalent.

```python Python theme={null}
await skyvern.launch_local_browser(
    *,
    headless: bool = False,
    port: int | None = None,
    args: list[str] | None = None,
    user_data_dir: str | None = None,
) -> SkyvernBrowser
```

**Parameters**

**headless** `bool`

Whether to run the browser in headless mode. Defaults to False.

Default: `False`

**port** `int | None`

The port number for the CDP endpoint. Anonymous launches use an OS-assigned port; explicitly configured launches retain DEFAULT\_CDP\_PORT.

Default: `None`

**args** `list[str] | None`

Additional command-line arguments to pass to Chromium. Defaults to None. Example: \["--disable-blink-features=AutomationControlled", "--window-size=1920,1080"]

Default: `None`

**user\_data\_dir** `str | None`

Default: `None`

**Returns** `SkyvernBrowser` — A browser instance with Skyvern capabilities.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.launch_local_browser()
    print(result)


asyncio.run(main())
```

***

### skyvern.aclose

Close Playwright, embedded server resources, and release all handles.

```python Python theme={null}
await skyvern.aclose() -> None
```

```typescript TypeScript theme={null}
skyvern.close(): Promise<void>
```

**Returns** `None` · TypeScript `Promise<void>`

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    await skyvern.aclose()


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
await skyvern.close();
```

## Pages

### browser.get\_working\_page

Get the most recent page or create a new one if none exists.

This method returns the last page in the browser context, or creates a new page
if the context has no pages. This is useful for continuing work on an existing
page without creating unnecessary new tabs.

```python Python theme={null}
await browser.get_working_page() -> SkyvernBrowserPage
```

```typescript TypeScript theme={null}
browser.getWorkingPage(): Promise<SkyvernBrowserPage>
```

**Returns** `SkyvernBrowserPage` · TypeScript `Promise<SkyvernBrowserPage>` — The most recent page wrapped with Skyvern capabilities.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    result = await browser.get_working_page()
    print(result)
    await browser.close()


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const result = await browser.getWorkingPage();
console.log(result);
await browser.close();
```

***

### browser.new\_page

Create a new page (tab) in the browser context.

This method always creates a new page, similar to opening a new tab in a browser.
The new page will have both Playwright's standard API and Skyvern's AI capabilities.

```python Python theme={null}
await browser.new_page() -> SkyvernBrowserPage
```

```typescript TypeScript theme={null}
browser.newPage(): Promise<SkyvernBrowserPage>
```

**Returns** `SkyvernBrowserPage` · TypeScript `Promise<SkyvernBrowserPage>` — A new page wrapped with Skyvern capabilities.

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    result = await browser.new_page()
    print(result)
    await browser.close()


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const result = await browser.newPage();
console.log(result);
await browser.close();
```

***

### browser.get\_page\_for

Wrap an existing Playwright Page with Skyvern capabilities.

Use this to create a SkyvernBrowserPage for a specific tab when you
already have a reference to the raw Playwright Page object.

> [!NOTE]
>
> Python only: the TypeScript SDK has no equivalent.

```python Python theme={null}
await browser.get_page_for(page: Page) -> SkyvernBrowserPage
```

**Parameters**

**page** `Page` *required*

**Returns** `SkyvernBrowserPage`

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    result = await browser.get_page_for(page=browser.pages[0])
    print(result)
    await browser.close()


asyncio.run(main())
```

***

### browser.close

Close the browser and optionally close the browser session.

This method closes the browser context. If the browser is associated with a
cloud browser session (has a browser\_session\_id), it will also close the
browser session via the API, marking it as completed.

```python Python theme={null}
await browser.close(**kwargs: Any) -> None
```

```typescript TypeScript theme={null}
browser.close(): Promise<void>
```

**Parameters**

\*\***kwargs** `Any`

Arguments passed to the underlying BrowserContext.close() method.

Sent only when you pass it · Python only

**Returns** `None` · TypeScript `Promise<void>`

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    await browser.close()


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
await browser.close();
```

***

## Browser properties

| Property | TypeScript | Type | Description |
| - | - | - | - |
| `browser.browser_session_id` | `browserSessionId` | `str \| None` | ID of the cloud browser session (`pbs_…`), or `None` for a local or CDP browser. |
| `browser.browser_address` | `browserAddress` | `str \| None` | CDP address the browser was connected through, if any. |
| `browser.app_url` | — | `str \| None` | Link to watch the cloud session live in the Skyvern app, if any. |
| `browser.local_cdp_port` | — | `int \| None` | CDP port of a browser started by `launch_local_browser`. |
| `browser.local_user_data_dir` | — | `str \| None` | Chrome user-data directory of a browser started by `launch_local_browser`. |
| `browser.skyvern` | `skyvern` | `Skyvern` | The `Skyvern` client this browser belongs to. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.