Repository: Skyvern-AI/skyvern

Stars: 21210

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands Copy Chapter

Python Backend Commands Copy Section

Code Quality & Testing Copy Section

Frontend Commands (in skyvern-frontend/) Copy Section

Database Management Copy Section

Architecture Overview Copy Chapter

Skyvern is a browser automation platform that uses LLMs and computer vision to interact with websites. The architecture consists of:

Core Components Copy Section

Key Directories Copy Section

Workflow System Copy Section

Data Flow Copy Section

Development Notes Copy Chapter

Environment Setup Copy Section

LLM Configuration Copy Section

Testing Strategy Copy Section

Code Style Copy Section

README.md Copy Chapter

<!-- DOCTOC SKIP -->

<h1 align="center">
<a href="https://www.skyvern.com">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="fern/images/skyvern_logo.png"/>
<img height="120" src="fern/images/skyvern_logo_blackbg.png"/>
</picture>
</a>
<br />
</h1>
<p align="center">
🐉 Automate Browser-based workflows using LLMs and Computer Vision 🐉
</p>
<p align="center">
<a href="https://www.skyvern.com/"><img src="https://img.shields.io/badge/Website-blue?logo=googlechrome&logoColor=black"/></a>
<a href="https://www.skyvern.com/docs/"><img src="https://img.shields.io/badge/Docs-yellow?logo=gitbook&logoColor=black"/></a>
<a href="https://discord.gg/fG2XXEuQX3"><img src="https://img.shields.io/discord/1212486326352617534?logo=discord&label=discord"/></a>
<!-- <a href="https://pepy.tech/project/skyvern" target="_blank"><img src="https://static.pepy.tech/badge/skyvern" alt="Total Downloads"/></a> -->
<a href="https://github.com/skyvern-ai/skyvern"><img src="https://img.shields.io/github/stars/skyvern-ai/skyvern" /></a>
<a href="https://github.com/Skyvern-AI/skyvern/blob/main/LICENSE"><img src="https://img.shields.io/github/license/skyvern-ai/skyvern"/></a>
<a href="https://twitter.com/skyvernai"><img src="https://img.shields.io/twitter/follow/skyvernai?style=social"/></a>
<a href="https://www.linkedin.com/company/95726232"><img src="https://img.shields.io/badge/Follow%20 on%20LinkedIn-8A2BE2?logo=linkedin"/></a>
</p>

Skyvern automates browser-based workflows using LLMs and computer vision. It provides a Playwright-compatible SDK that adds AI functionality on top of playwright, as well as a no-code workflow builder to help both technical and non-technical users automate manual workflows on any website, replacing brittle or unreliable automation solutions.

<p align="center">
<img src="fern/images/geico_shu_recording_cropped.gif"/>
</p>

Traditional approaches to browser automations required writing custom scripts for websites, often relying on DOM parsing and XPath-based interactions which would break whenever the website layouts changed.

Instead of only relying on code-defined XPath interactions, Skyvern relies on Vision LLMs to learn and interact with the websites.

How it works

Skyvern uses a swarm of agents to comprehend a website, and plan and execute its actions:

<picture>
<source media="(prefers-color-scheme: dark)" srcset="fern/images/skyvern_2_0_system_diagram.png" />
<img src="fern/images/skyvern_2_0_system_diagram.png" />
</picture>

This approach has a few advantages:

1. Skyvern can operate on websites it's never seen before, as it's able to map visual elements to actions necessary to complete a workflow, without any customized code
1. Skyvern is resistant to website layout changes, as there are no pre-determined XPaths or other selectors our system is looking for while trying to navigate
1. Skyvern is able to take a single workflow and apply it to a large number of websites, as it's able to reason through the interactions necessary to complete the workflow
A detailed technical report can be found here.

Demo

Quickstart

Skyvern Cloud Copy Chapter

If you'd like to try it out, navigate to app.skyvern.com and create an account.

Run Locally (UI + Server) Copy Chapter

Choose your preferred setup method:

Option A: pip install (Recommended) Copy Section

Dependencies needed:
- Python 3.11.x, works with 3.12, not ready yet for 3.13
- NodeJS & NPM

Additionally, for Windows:
- Rust
- VS Code with C++ dev tools and Windows SDK

#### 1. Install Skyvern

pip install skyvern

#### 2. Run Skyvern

skyvern quickstart

Option B: Docker Compose Copy Section

1. Install Docker Desktop
2. Clone the repository:

git clone https://github.com/skyvern-ai/skyvern.git && cd skyvern

pip install skyvern && skyvern quickstart

SDK Copy Chapter

Skyvern is a Playwright extension that adds AI-powered browser automation. It gives you the full power of Playwright with additional AI capabilities—use natural language prompts to interact with elements, extract data, and automate complex multi-step workflows.

Installation:
- Python: pip install skyvern then run skyvern quickstart for local setup
- TypeScript: npm install @skyvern/client

AI-Powered Page Commands Copy Section

Skyvern adds four core AI commands directly on the page object:

| Command | Description |
|---------|-------------|
| page.act(prompt) | Perform actions using natural language (e.g., "Click the login button") |
| page.extract(prompt, schema) | Extract structured data from the page with optional JSON schema |
| page.validate(prompt) | Validate page state, returns bool (e.g., "Check if user is logged in") |
| page.prompt(prompt, schema) | Send arbitrary prompts to the LLM with optional response schema |

Additionally, page.agent provides higher-level workflow commands:

| Command | Description |
|---------|-------------|
| page.agent.run_task(prompt) | Execute complex multi-step tasks |
| page.agent.login(credential_type, credential_id) | Authenticate with stored credentials (Skyvern, Bitwarden, 1Password) |
| page.agent.download_files(prompt) | Navigate and download files |
| page.agent.run_workflow(workflow_id) | Execute pre-built workflows |

AI-Augmented Playwright Actions Copy Section

All standard Playwright actions support an optional prompt parameter for AI-powered element location:

| Action | Playwright | AI-Augmented |
|--------|------------|--------------|
| Click | page.click("#btn") | page.click(prompt="Click login button") |
| Fill | page.fill("#email", "[email protected]") | page.fill(prompt="Email field", value="[email protected]") |
| Select | page.select_option("#country", "US") | page.select_option(prompt="Country dropdown", value="US") |
| Upload | page.upload_file("#file", "doc.pdf") | page.upload_file(prompt="Upload area", files="doc.pdf") |

Three interaction modes:

1. Traditional Playwright - CSS/XPath selectors

await page.click("#submit-button")
2. AI-powered - natural language

await page.click(prompt="Click the green Submit button")
3. AI fallback - tries selector first, falls back to AI if it fails

await page.click("#submit-btn", prompt="Click the Submit button")

Core AI Commands - Examples Copy Section

act - Perform actions using natural language

await page.act("Click the login button and wait for the dashboard to load")
extract - Extract structured data with optional JSON schema

result = await page.extract("Get the product name and price")
result = await page.extract(
    prompt="Extract order details",
    schema={"order_id": "string", "total": "number", "items": "array"}
)
validate - Check page state (returns bool)

is_logged_in = await page.validate("Check if the user is logged in")
prompt - Send arbitrary prompts to the LLM

summary = await page.prompt("Summarize what's on this page")

Quick Start Examples Copy Section

Run via UI:

skyvern run all

Python SDK:

from skyvern import Skyvern
Local mode

skyvern = Skyvern.local()
Or connect to Skyvern Cloud

skyvern = Skyvern(api_key="your-api-key")
Launch browser and get page

browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
Mix Playwright with AI-powered actions

await page.goto("https://example.com")
await page.click("#login-button")  # Traditional Playwright
await page.agent.login(credential_type="skyvern", credential_id="cred_123")  # AI login
await page.click(prompt="Add first item to cart")  # AI-augmented click
await page.agent.run_task("Complete checkout with: John Snow, 12345")  # AI task

TypeScript SDK:

import { Skyvern } from "@skyvern/client";
const skyvern = new Skyvern({ apiKey: "your-api-key" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
// Mix Playwright with AI-powered actions
await page.goto("https://example.com");
await page.click("#login-button");  // Traditional Playwright
await page.agent.login("skyvern", { credentialId: "cred_123" });  // AI login
await page.click({ prompt: "Add first item to cart" });  // AI-augmented click
await page.agent.runTask("Complete checkout with: John Snow, 12345");  // AI task
await browser.close();

Simple task execution:

from skyvern import Skyvern
skyvern = Skyvern()
task = await skyvern.run_task(prompt="Find the top post on hackernews today")
print(task)

Advanced Usage Copy Chapter

Control your own browser (Chrome) Copy Section

1. Just With Python Code

from skyvern import Skyvern
The path to your Chrome browser. This example path is for Mac.

browser_path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
skyvern = Skyvern(
    base_url="http://localhost:8000",
    api_key="YOUR_API_KEY",
    browser_path=browser_path,
)
task = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
)

2. With Skyvern Service

Add two variables to your .env file:

The path to your Chrome browser. This example path is for Mac.

CHROME_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
BROWSER_TYPE=cdp-connect

Restart Skyvern service skyvern run all and run the task through UI or code

Connect Skyvern Cloud to your local browser Copy Section

Let Skyvern Cloud control a Chrome browser running on your machine — with all your existing cookies, logins, and extensions. Useful for automating sites where you're already logged in or behind a VPN.

One command to start Chrome + create a tunnel to Skyvern Cloud

skyvern browser serve --tunnel

Then use the tunnel URL in your task:

from skyvern import Skyvern
skyvern = Skyvern(api_key="your-api-key")
task = await skyvern.run_task(
    prompt="Download the latest invoice from my account",
    browser_address="https://abc123.ngrok-free.dev",
)

See the full documentation for all options, manual tunnel setup, and troubleshooting.

Get consistent output schema from your run Copy Section

from skyvern import Skyvern
skyvern = Skyvern()
task = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    data_extraction_schema={
        "type": "object",
        "properties": {
            "title": {
                "type": "string",
                "description": "The title of the top post"
            },
            "url": {
                "type": "string",
                "description": "The URL of the top post"
            },
            "points": {
                "type": "integer",
                "description": "Number of points the post has received"
            }
        }
    }
)

Helpful commands to debug issues Copy Section

Launch the Skyvern Server Separately*

skyvern run server
Launch the Skyvern UI

skyvern run ui
Check status of the Skyvern service

skyvern status
Stop the Skyvern service

skyvern stop all
Stop the Skyvern UI

skyvern stop ui
Stop the Skyvern Server Separately

skyvern stop server

Performance & Evaluation

Skyvern has SOTA performance on the WebBench benchmark with a 64.4% accuracy. The technical report + evaluation can be found here

<p align="center">
<img src="fern/images/performance/webbench_overall.png"/>
</p>

Performance on WRITE tasks (eg filling out forms, logging in, downloading files, etc) Copy Chapter

Skyvern is the best performing agent on WRITE tasks (eg filling out forms, logging in, downloading files, etc), which is primarily used for RPA (Robotic Process Automation) adjacent tasks.

<p align="center">
<img src="fern/images/performance/webbench_write.png"/>
</p>

Skyvern Features

Skyvern Tasks Copy Chapter

Tasks require you to specify a url, prompt, and can optionally include a data schema (if you want the output to conform to a specific schema) and error codes (if you want Skyvern to stop running in specific situations).

<p align="center">
<img src="fern/images/skyvern_2_0_screenshot.png"/>
</p>

Skyvern Workflows Copy Chapter

For example, if you wanted to download all invoices newer than January 1st, you could create a workflow that first navigated to the invoices page, then filtered down to only show invoices newer than January 1st, extracted a list of all eligible invoices, and iterated through each invoice to download it.

Another example is if you wanted to automate purchasing products from an e-commerce store, you could create a workflow that first navigated to the desired product, then added it to a cart. Second, it would navigate to the cart and validate the cart state. Finally, it would go through the checkout process to purchase the items.

Supported workflow features include:
1. Browser Task
1. Browser Action
1. Data Extraction
1. Validation
1. For Loops
1. File parsing
1. Sending emails
1. Text Prompts
1. HTTP Request Block
1. Custom Code Block
1. Uploading files to block storage
1. (Coming soon) Conditionals

<p align="center">
<img src="fern/images/block_example_v2.png"/>
</p>

Livestreaming Copy Chapter

Form Filling Copy Chapter

Data Extraction Copy Chapter

You can also specify a data_extraction_schema directly within the main prompt to tell Skyvern exactly what data you'd like to extract from the website, in jsonc format. Skyvern's output will be structured in accordance to the supplied schema.

File Downloading Copy Chapter

Authentication Copy Chapter

<p align="center">
<img src="fern/images/secure_password_task_example.png"/>
</p>

🔐 2FA Support (TOTP) Copy Section

Examples include:
1. QR-based 2FA (e.g. Google Authenticator, Authy)
1. Email based 2FA
1. SMS based 2FA

🔐 Learn more about 2FA support here.

Password Manager Integrations Copy Section

Model Context Protocol (MCP) Copy Chapter

Skyvern supports the Model Context Protocol (MCP) to allow you to use any LLM that supports MCP.

See the MCP documentation here

Zapier / Make.com / N8N Integration Copy Chapter

* Zapier
* Make.com
* N8N

🔐 Learn more about 2FA support here.

Real-world examples of Skyvern

Invoice Downloading on many different websites Copy Chapter

<p align="center">
<img src="fern/images/invoice_downloading.gif"/>
</p>

Automate the job application process Copy Chapter

Automate materials procurement for a manufacturing company Copy Chapter

Navigating to government websites to register accounts or fill out forms Copy Chapter

Filling out random contact us forms Copy Chapter

Retrieving insurance quotes from insurance providers in any language Copy Chapter

💡 See it in action

<p align="center">
<img src="fern/images/geico_shu_recording_cropped.gif"/>
</p>

Contributor Setup

uv sync --group dev

uv run skyvern quickstart

Documentation

More extensive documentation can be found on our 📕 docs page. Please let us know if something is unclear or missing by opening an issue or reaching out to us via email or discord.

Supported LLMs

#### Environment Variables

##### OpenAI
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_OPENAI| Register OpenAI models | Boolean | true, false |
| OPENAI_API_KEY | OpenAI API Key | String | sk-1234567890 |
| OPENAI_API_BASE | OpenAI API Base, optional | String | https://openai.api.base |
| OPENAI_ORGANIZATION | OpenAI Organization ID, optional | String | your-org-id |

Recommended LLM_KEY: OPENAI_GPT5, OPENAI_GPT5_2, OPENAI_GPT4_1, OPENAI_O3, OPENAI_O4_MINI

##### Anthropic
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_ANTHROPIC | Register Anthropic models| Boolean | true, false |
| ANTHROPIC_API_KEY | Anthropic API key| String | sk-1234567890 |

Recommended LLM_KEY: ANTHROPIC_CLAUDE4.5_OPUS, ANTHROPIC_CLAUDE4.5_SONNET, ANTHROPIC_CLAUDE4_OPUS, ANTHROPIC_CLAUDE4_SONNET

##### Azure OpenAI
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_AZURE | Register Azure OpenAI models | Boolean | true, false |
| AZURE_API_KEY | Azure deployment API key | String | sk-1234567890 |
| AZURE_DEPLOYMENT | Azure OpenAI Deployment Name | String | skyvern-deployment|
| AZURE_API_BASE | Azure deployment api base url| String | https://skyvern-deployment.openai.azure.com/|
| AZURE_API_VERSION | Azure API Version| String | 2024-02-01|

Recommended LLM_KEY: AZURE_OPENAI

##### AWS Bedrock
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_BEDROCK | Register AWS Bedrock models. To use AWS Bedrock, you need to make sure your AWS configurations are set up correctly first. | Boolean | true, false |

Recommended LLM_KEY: BEDROCK_ANTHROPIC_CLAUDE4.5_OPUS_INFERENCE_PROFILE, BEDROCK_ANTHROPIC_CLAUDE4.5_SONNET_INFERENCE_PROFILE, BEDROCK_ANTHROPIC_CLAUDE4_OPUS_INFERENCE_PROFILE

##### Gemini
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_GEMINI | Register Gemini models| Boolean | true, false |
| GEMINI_API_KEY | Gemini API Key| String | your_google_gemini_api_key|

Recommended LLM_KEY: GEMINI_3.0_FLASH, GEMINI_2.5_PRO, GEMINI_2.5_FLASH, GEMINI_2.5_PRO_PREVIEW, GEMINI_2.5_FLASH_PREVIEW

##### Ollama
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_OLLAMA| Register local models via Ollama | Boolean | true, false |
| OLLAMA_SERVER_URL | URL for your Ollama server | String | http://host.docker.internal:11434 |
| OLLAMA_MODEL | Ollama model name to load | String | qwen2.5:7b-instruct |
| OLLAMA_SUPPORTS_VISION | Enable vision support | Boolean | true, false |

Recommended LLM_KEY: OLLAMA

Note: Set OLLAMA_SUPPORTS_VISION=true for vision models like qwen3-vl, llava, etc.

##### OpenRouter
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_OPENROUTER| Register OpenRouter models | Boolean | true, false |
| OPENROUTER_API_KEY | OpenRouter API key | String | sk-1234567890 |
| OPENROUTER_MODEL | OpenRouter model name | String | mistralai/mistral-small-3.1-24b-instruct |
| OPENROUTER_API_BASE | OpenRouter API base URL | String | https://api.openrouter.ai/v1 |

Recommended LLM_KEY: OPENROUTER

##### OpenAI-Compatible
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| ENABLE_OPENAI_COMPATIBLE| Register a custom OpenAI-compatible API endpoint | Boolean | true, false |
| OPENAI_COMPATIBLE_MODEL_NAME | Model name for OpenAI-compatible endpoint | String | yi-34b, gpt-3.5-turbo, mistral-large, etc.|
| OPENAI_COMPATIBLE_API_KEY | API key for OpenAI-compatible endpoint | String | sk-1234567890|
| OPENAI_COMPATIBLE_API_BASE | Base URL for OpenAI-compatible endpoint | String | https://api.together.xyz/v1, http://localhost:8000/v1, etc.|
| OPENAI_COMPATIBLE_API_VERSION | API version for OpenAI-compatible endpoint, optional| String | 2023-05-15|
| OPENAI_COMPATIBLE_MAX_TOKENS | Maximum tokens for completion, optional| Integer | 4096, 8192, etc.|
| OPENAI_COMPATIBLE_TEMPERATURE | Temperature setting, optional| Float | 0.0, 0.5, 0.7, etc.|
| OPENAI_COMPATIBLE_SUPPORTS_VISION | Whether model supports vision, optional| Boolean | true, false|

Supported LLM Key: OPENAI_COMPATIBLE

##### General LLM Configuration
| Variable | Description| Type | Sample Value|
| -------- | ------- | ------- | ------- |
| LLM_KEY | The name of the model you want to use | String | See supported LLM keys above |
| SECONDARY_LLM_KEY | The name of the model for mini agents skyvern runs with | String | See supported LLM keys above |
| LLM_CONFIG_MAX_TOKENS | Override the max tokens used by the LLM | Integer | 128000 |

Feature Roadmap

- [x] Open Source - Open Source Skyvern's core codebase
- [x] Workflow support - Allow support to chain multiple Skyvern calls together
- [x] Improved context - Improve Skyvern's ability to understand content around interactable elements by introducing feeding relevant label context through the text prompt
- [x] Cost Savings - Improve Skyvern's stability and reduce the cost of running Skyvern by optimizing the context tree passed into Skyvern
- [x] Self-serve UI - Deprecate the Streamlit UI in favour of a React-based UI component that allows users to kick off new jobs in Skyvern
- [x] Workflow UI Builder - Introduce a UI to allow users to build and analyze workflows visually
- [x] Chrome Viewport streaming - Introduce a way to live-stream the Chrome viewport to the user's browser (as a part of the self-serve UI)
- [x] Past Runs UI - Deprecate the Streamlit UI in favour of a React-based UI that allows you to visualize past runs and their results
- [X] Auto workflow builder ("Observer") mode - Allow Skyvern to auto-generate workflows as it's navigating the web to make it easier to build new workflows
- [x] Prompt Caching - Introduce a caching layer to the LLM calls to dramatically reduce the cost of running Skyvern (memorize past actions and repeat them!)
- [x] Web Evaluation Dataset - Integrate Skyvern with public benchmark tests to track the quality of our models over time
- [ ] Improved Debug mode - Allow Skyvern to plan its actions and get "approval" before running them, allowing you to debug what it's doing and more easily iterate on the prompt
- [ ] Chrome Extension - Allow users to interact with Skyvern through a Chrome extension (incl voice mode, saving tasks, etc.)
- [ ] Skyvern Action Recorder - Allow Skyvern to watch a user complete a task and then automatically generate a workflow for it
- [ ] Interactable Livestream - Allow users to interact with the livestream in real-time to intervene when necessary (such as manually submitting sensitive forms)
- [ ] Integrate LLM Observability tools - Integrate LLM Observability tools to allow back-testing prompt changes with specific data sets + visualize the performance of Skyvern over time
- [x] Langchain Integration - Create langchain integration in langchain_community to use Skyvern as a "tool".

Contributing

We welcome PRs and suggestions! Don't hesitate to open a PR/issue or to reach out to us via email or discord.
Please have a look at our contribution guide and
"Help Wanted" issues to get started!

If you want to chat with the skyvern repository to get a high level overview of how it is structured, how to build off it, and how to resolve usage questions, check out Code Sage.

Telemetry

By Default, Skyvern collects basic usage statistics to help us understand how Skyvern is being used. If you would like to opt-out of telemetry, please set the SKYVERN_TELEMETRY environment variable to false.

License

If you have any questions or concerns around licensing, please contact us and we would be happy to help.

Star History