Connect Skyvern to Your Local Browser

Why connect your local browser?

With skyvern browser serve, Skyvern Cloud can control a Chrome browser running on your machine — using your existing cookies, sessions, extensions, and saved passwords. This is useful when:

You need to automate a site where you’re already logged in
The target site is behind a VPN or firewall that only your machine can reach
You want Skyvern to use browser extensions you’ve already installed

Quick start

$ skyvern browser serve --tunnel

This launches Chrome on your machine, starts a CDP proxy server, and creates an ngrok tunnel so Skyvern Cloud can connect automatically.

The --tunnel flag requires ngrok installed and authenticated (ngrok authtoken <your-token>).

Manual tunnel setup

$ # 1. Start the browser server
$ skyvern browser serve
$ 
$ # 2. In a separate terminal, create a tunnel
$ ngrok http 9222
$ 
$ # 3. Copy the ngrok URL and use it as browser_address in your task

Run a task on your local browser

Pass the tunnel URL as browser_address:

1 from skyvern import Skyvern
2 
3 skyvern = Skyvern(api_key="YOUR_API_KEY")
4 
5 result = await skyvern.run_task(
6     prompt="Download the latest invoice from my account",
7     browser_address="wss://abc123.ngrok-free.dev",
8 )

How it works

┌──────────────────────────────────────────────────────┐
│  Your machine                                        │
│                                                      │
│  ┌────────────┐   CDP (internal)   ┌──────────────┐  │
│  │   Chrome    │◄─────────────────►│  Unified     │  │
│  │  (port      │   port 10222      │  Server      │  │
│  │   10222)    │                   │  (port 9222) │  │
│  └────────────┘                   └──────┬───────┘  │
│                                          │           │
└──────────────────────────────────────────┼───────────┘
                                           │
                              ngrok / tunnel│
                                           │
                                    ┌──────▼───────┐
                                    │ Skyvern Cloud│
                                    └──────────────┘

Launches Chrome with CDP enabled on an internal port (exposed_port + 1000)
Starts a proxy server on the exposed port (default 9222) that forwards CDP traffic to Chrome
Optionally creates a tunnel (--tunnel) so Skyvern Cloud can reach it from the internet

CLI options

Option	Default	Description
`--port`	`9222`	Port for the proxy server. Chrome uses `port + 1000` internally.
`--profile-dir`	`~/.skyvern/chrome-profile`	Chrome user data directory. Point this at an existing profile to reuse cookies and logins.
`--download-dir`	`~/.skyvern/downloads/{browser_id}`	Directory for browser downloads.
`--api-key`	(none)	API key for authenticating incoming requests.
`--headless`	`false`	Run Chrome in headless mode (no visible window).
`--chrome-path`	(auto-detect)	Path to Chrome/Chromium executable.
`--tunnel`	`false`	Automatically start an ngrok tunnel.
`--json`	`false`	Output connection info as JSON (for scripting).

The --api-key option can also be set via the SKYVERN_BROWSER_SERVE_API_KEY environment variable.

Security

Warning: When you run skyvern browser serve without --api-key and expose it via a tunnel, anyone with the tunnel URL has full remote control of your Chrome browser — including access to all logged-in sessions, cookies, and saved passwords.

Always use --api-key when exposing your browser:

$ skyvern browser serve --api-key "your-skyvern-api-key" --tunnel

Skyvern Cloud automatically sends the correct API key when connecting. For additional security (IP allowlisting, mTLS, VPN), contact support@skyvern.com.