Connect Skyvern to Your Local Browser - Skyvern (original) (raw)

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.

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:

How it works

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

skyvern browser serve:

1. Launches Chrome with CDP (Chrome DevTools Protocol) enabled on an internal port
2. Starts a proxy server on the exposed port (default 9222) that forwards CDP traffic to Chrome
3. Optionally creates a tunnel (--tunnel) so Skyvern Cloud can reach it from the internet

CLI options

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

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

Troubleshooting

Next steps