Connect Skyvern to Your Local Browser

Want Skyvern Cloud to automate a site where you’re already logged in? With skyvern browser serve, Skyvern Cloud can control a Chrome browser running on your machine, using your existing cookies, sessions, extensions, and saved passwords. Common use cases:

Automate sites where you’re already authenticated (no need to re-login)
Reach internal tools behind a VPN or firewall
Use browser extensions you’ve already installed (ad blockers, auth tools, etc.)
Keep all browser data on your own machine

Quick start

One command starts Chrome on your machine and creates a tunnel so Skyvern Cloud can connect:

skyvern browser serve --tunnel

That’s it. The CLI launches Chrome, starts a local proxy server, and opens an ngrok tunnel. You’ll see a tunnel URL in the output; pass it as browser_address when running tasks.

The --tunnel flag requires ngrok to be installed and authenticated. Run ngrok authtoken <your-token> once to set it up.

Step-by-step (manual tunnel)

If you prefer to manage the tunnel yourself:

# 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

Once the tunnel is running, pass the tunnel URL as browser_address:

import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key="YOUR_API_KEY")

    result = await client.run_task(
        prompt="Download the latest invoice from my account",
        browser_address="wss://abc123.ngrok-free.dev",
    )

    print(f"Status: {result.status}")
    print(f"Output: {result.output}")

asyncio.run(main())

import { Skyvern } from "@skyvern/client";

async function main() {
  const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });

  const result = await client.runTask({
    body: {
      prompt: "Download the latest invoice from my account",
      browser_address: "wss://abc123.ngrok-free.dev",
    },
    waitForCompletion: true,
  });

  console.log(`Status: ${result.status}`);
  console.log(`Output: ${JSON.stringify(result.output)}`);
}

main();

curl -X POST "https://api.skyvern.com/v1/run/tasks" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Download the latest invoice from my account",
    "browser_address": "wss://abc123.ngrok-free.dev"
  }'

How it works

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

skyvern browser serve:

Launches Chrome with CDP (Chrome DevTools Protocol) enabled on an internal port
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. See Security.
`--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. Requires `ngrok` installed.
`--json`	`false`	Output connection info as JSON (for scripting). Cannot combine with `--tunnel`.

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

Examples

# Use a specific Chrome profile (reuse your existing logins)
skyvern browser serve --profile-dir ~/Library/Application\ Support/Google/Chrome/Default

# Run headless with auto-tunnel
skyvern browser serve --headless --tunnel

# Custom port with API key authentication
skyvern browser serve --port 8222 --api-key "my-secret-key"

# Output connection info as JSON (useful for scripting)
skyvern browser serve --json

Security

Read this section before exposing your browser to the internet.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. This includes access to all logged-in sessions, cookies, saved passwords, and anything visible in the browser.

API key authentication

Use your Skyvern API key (from Settings) with the --api-key flag to require authentication on every incoming request:

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

Or set it via environment variable:

export SKYVERN_BROWSER_SERVE_API_KEY="your-skyvern-api-key"
skyvern browser serve

When enabled, all requests without a valid x-api-key header receive a 401 Unauthorized response. Skyvern Cloud automatically sends the correct API key when connecting.

Additional security measures

The built-in API key provides basic protection. For additional security such as IP allowlisting, mTLS, or VPN-based access, contact support@skyvern.com.

When to use this vs other options

Approach	When to use
Connect to your local browser (`skyvern browser serve`)	You want Skyvern Cloud to use your local browser with your existing sessions
Browser Sessions	You want Skyvern Cloud to manage the browser entirely in the cloud
Browser Profiles	You want to save and reuse cookies/storage state across cloud sessions
CDP Connect (self-hosted)	You’re running Skyvern locally and want to connect to an existing Chrome instance

Troubleshooting

ngrok not found

Install ngrok from ngrok.com/download and authenticate it:

ngrok authtoken <your-token>

Chrome not found

Use --chrome-path to specify the path to your Chrome executable:

# macOS
skyvern browser serve --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Linux
skyvern browser serve --chrome-path /usr/bin/google-chrome

# Windows
skyvern browser serve --chrome-path "C:\Program Files\Google\Chrome\Application\chrome.exe"

Port already in use

Another process is using port 9222. Either stop that process or use a different port:

skyvern browser serve --port 8222

Tunnel connection drops

ngrok free tier tunnels have connection limits. For production use, consider an ngrok paid plan or contact support@skyvern.com for alternative tunnel options.

Getting Started

Core Features

Browser Automation

Agent Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Connect Skyvern to Your Local Browser

Quick start

Step-by-step (manual tunnel)

Run a task on your local browser

How it works

CLI options

Examples

Security

API key authentication

Additional security measures

When to use this vs other options

Troubleshooting

Next steps

Browser Sessions

Browser Profiles

​Quick start

​Step-by-step (manual tunnel)

​Run a task on your local browser

​How it works

​CLI options

​Examples

​Security

​API key authentication

​Additional security measures

​When to use this vs other options

​Troubleshooting

​Next steps

Browser Sessions

Browser Profiles

Quick start

Step-by-step (manual tunnel)

Run a task on your local browser

How it works

CLI options

Examples

Security

API key authentication

Additional security measures

When to use this vs other options

Troubleshooting

Next steps