skyvern

name: skyvern description: > AI-powered browser automation using Skyvern (self-hosted only). Automate web workflows, fill forms, extract data, and navigate multi-step processes using Vision LLMs and Playwright. Skyvern uses a Planner→Agent→Validator multi-agent architecture with computer vision to interact with web pages semantically — no brittle CSS/XPath selectors. All LLM inference routes through LiteLLM; use OpenRouter, Ollama, any OpenAI-compatible endpoint, or your own proxy (ZenMux, Z.AI, Nebius, etc.). Never use the Skyvern cloud API. Always self-host. version: 2.0.0

Skyvern — AI Browser Automation (Self-Hosted Expert Reference)

Policy: We NEVER use Skyvern's hosted cloud API (api.skyvern.com). All deployments are self-hosted, routing LLM calls through our own providers: OpenRouter, ZenMux, Z.AI, Nebius Token Factory, Ollama, or any OpenAI-compatible endpoint.

Instructions

Step 1: Fetch Latest Docs (Always)

Before implementing, use web tools to pull current state from these canonical sources:

Step 2: Architecture Deep Dive

2.1 How Skyvern Works

Skyvern is inspired by BabyAGI/AutoGPT but adds real browser control via Playwright. It uses a swarm of agents to comprehend a website, plan actions, and execute them:

┌─────────────────────────────────────────────────────┐
│                  Skyvern 2.0 Engine                 │
│                                                     │
│  ┌──────────┐   ┌──────────┐   ┌──────────────┐    │
│  │ Planner  │──→│  Agent   │──→│  Validator   │    │
│  │  Agent   │   │ (Actor)  │   │   Agent      │    │
│  └──────────┘   └──────────┘   └──────────────┘    │
│       │              │               │              │
│       └──────────────┴───────────────┘              │
│                      │                              │
│              ┌───────▼───────┐                      │
│              │   Playwright  │                      │
│              │   (Browser)   │                      │
│              └───────────────┘                      │
│                      │                              │
│              ┌───────▼───────┐                      │
│              │   LiteLLM     │ ◄── All LLM calls    │
│              │   (Gateway)   │     route through     │
│              └───────────────┘     this layer        │
└─────────────────────────────────────────────────────┘

Key advantages:

1. Zero-shot — operates on websites never seen before
2. Layout-resistant — no XPath/CSS selectors; vision-based element discovery
3. Multi-site reusable — one workflow runs across different websites
4. Computer Vision — screenshots → LLM reasoning → action plan → Playwright execution

2.2 Core Concepts

2.3 Workflow Block Taxonomy

Browser Task (recommended block): accepts natural-language prompt, autonomously navigates.

• Skyvern 2.0 fields: URL, Prompt, Max Steps, Disable Cache
• Skyvern 1.0 fields: URL, Prompt + Advanced (completion condition, action history, download triggers)

Browser Action: single granular action (click, type, select, upload) — no goal-seeking.

Extraction: turns current page content into structured JSON without navigation.

Step 3: Self-Hosted Deployment

3.1 Option A: pip install (Recommended for dev)

pip install skyvern  # or: uv pip install skyvern
skyvern quickstart   # interactive wizard: DB, LLM provider, browser mode, MCP

The quickstart wizard will:

1. Set up database (SQLite default since v1.0.31+, or PostgreSQL)
2. Configure your LLM provider via .env
3. Choose browser mode (headless, headful, connect to existing Chrome)
4. Generate local API credentials (SKYVERN_API_KEY)
5. Optionally configure MCP for Claude Code/Desktop/Cursor/Windsurf
6. Download Chromium browser

3.2 Option B: Docker Compose

git clone https://github.com/Skyvern-AI/skyvern.git && cd skyvern
cp .env.example .env
# Edit .env — configure LLM provider (see Step 4)
docker compose up -d
# UI at http://localhost:8080

3.3 Option C: Kubernetes

Helm charts and manifests in kubernetes-deployment/ directory. See docs for scaling config.

Step 4: LLM Configuration (BYOM — Bring Your Own Model)

Critical: All LLM routing goes through LiteLLM internally. The LLMConfigRegistry (at skyvern/forge/sdk/api/llm/config_registry.py, ~1946 lines) registers model configs at startup based on ENABLE_* environment flags.

4.1 Supported Provider Matrix

4.2 OpenRouter Configuration (Our Primary Path)

# .env
ENABLE_OPENROUTER=true
LLM_KEY=OPENROUTER
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=minimax/minimax-m2.5  # Any model on OpenRouter
# OPENROUTER_API_BASE=https://openrouter.ai/api/v1  # default

Under the hood — the config_registry.py registers it as:

LLMConfigRegistry.register_config(
    "OPENROUTER",
    LLMConfig(
        "openrouter/{model_name}",
        ["OPENROUTER_API_KEY", "OPENROUTER_MODEL"],
        supports_vision=settings.LLM_CONFIG_SUPPORT_VISION,
        max_completion_tokens=settings.LLM_CONFIG_MAX_TOKENS,
        litellm_params=LiteLLMParams(
            api_key=settings.OPENROUTER_API_KEY,
            api_base=settings.OPENROUTER_API_BASE,
            model_info={"model_name": f"openrouter/{model_name}"},
        ),
    ),
)

Dynamic OpenRouter model resolution: If LLM_KEY starts with openrouter/, the registry creates a config on-the-fly without needing explicit registration.

4.3 OpenAI-Compatible Endpoint (ZenMux, Z.AI, Nebius, LM Studio, vLLM, etc.)

# .env
ENABLE_OPENAI_COMPATIBLE=true
LLM_KEY=OPENAI_COMPATIBLE

# Required
OPENAI_COMPATIBLE_API_KEY=your-key-here
OPENAI_COMPATIBLE_API_BASE=https://your-proxy.example.com/v1
OPENAI_COMPATIBLE_MODEL_NAME=your-model-name

# Optional
OPENAI_COMPATIBLE_MODEL_KEY=OPENAI_COMPATIBLE    # Custom registry key
OPENAI_COMPATIBLE_SUPPORTS_VISION=true            # Enable vision support
OPENAI_COMPATIBLE_ADD_ASSISTANT_PREFIX=false
OPENAI_COMPATIBLE_MAX_TOKENS=128000
OPENAI_COMPATIBLE_TEMPERATURE=0.7
OPENAI_COMPATIBLE_REASONING_EFFORT=medium
OPENAI_COMPATIBLE_API_VERSION=                    # If needed

Under the hood — registers with openai/ prefix for LiteLLM routing:

LLMConfig(
    f"openai/{openai_compatible_model_name}",  # LiteLLM requires this prefix
    required_env_vars,
    supports_vision=settings.OPENAI_COMPATIBLE_SUPPORTS_VISION,
    litellm_params=LiteLLMParams(
        api_key=settings.OPENAI_COMPATIBLE_API_KEY,
        api_base=settings.OPENAI_COMPATIBLE_API_BASE,
        model_info={"model_name": f"openai/{openai_compatible_model_name}"},
    ),
)

4.4 Ollama (Fully Local)

# .env
ENABLE_OLLAMA=true
LLM_KEY=OLLAMA
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_MODEL=llava:latest
OLLAMA_SUPPORTS_VISION=true

4.5 Multi-Model Setup

Skyvern supports LLM_KEY for the primary model and SECONDARY_LLM_KEY for mini agents:

LLM_KEY=OPENROUTER                         # Primary (Planner + Actor)
SECONDARY_LLM_KEY=OLLAMA                   # Secondary (mini validation tasks)
LLM_CONFIG_MAX_TOKENS=128000               # Global max tokens override

4.6 General LLM Tuning Variables

Step 5: SDK Usage (Playwright + AI Hybrid)

Skyvern's SDK is a Playwright extension that adds AI-powered commands.

5.1 Python SDK — Three Interaction Modes

from skyvern import Skyvern

# Self-hosted local mode (our standard)
skyvern = Skyvern.local()
# Or explicit:
skyvern = Skyvern(
    base_url="http://localhost:8000",
    api_key="YOUR_LOCAL_SKYVERN_API_KEY"
)

browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()

# Mode 1: Traditional Playwright (CSS/XPath selectors)
await page.goto("https://example.com")
await page.click("#submit-button")

# Mode 2: AI-powered (natural language)
await page.click(prompt="Click the green Submit button")

# Mode 3: AI fallback (tries selector first, AI if it fails)
await page.click("#submit-btn", prompt="Click the Submit button")

5.2 Core AI Page Commands

5.3 Agent-Level Commands

5.4 Simple Task Execution

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"},
            "url": {"type": "string"},
            "points": {"type": "integer"}
        }
    }
)
print(task)

5.5 TypeScript SDK

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

const skyvern = new Skyvern({
    baseUrl: "http://localhost:8000",
    apiKey: "YOUR_LOCAL_KEY"
});
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();

await page.goto("https://example.com");
await page.agent.runTask("Complete checkout with: John Snow, 12345");
await browser.close();

5.6 REST API (Self-Hosted)

# Create a task
curl -X POST "http://localhost:8000/api/v1/tasks" \
  -H "Authorization: Bearer $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "navigation_goal": "Find the pricing page and extract all plan details",
    "data_extraction_schema": {
      "type": "object",
      "properties": {
        "plans": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "price": {"type": "string"}
            }
          }
        }
      }
    }
  }'

# Get task result
curl "http://localhost:8000/api/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $SKYVERN_API_KEY"

5.7 Task Parameters Reference

5.8 Run Status Values

queued → running → completed | failed | terminated | timed_out | canceled

Step 6: MCP Server

Skyvern exposes an MCP server for integration with Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Hermes, and OpenClaw.

6.1 Configuration

{
  "mcpServers": {
    "Skyvern": {
      "command": "/path/to/python3",
      "args": ["-m", "skyvern", "run", "mcp"],
      "env": {
        "SKYVERN_BASE_URL": "http://localhost:8000",
        "SKYVERN_API_KEY": "YOUR_LOCAL_KEY"
      }
    }
  }
}

6.2 Quickstart MCP auto-setup

During skyvern quickstart, if you choose Claude Code, it will:

• Write .mcp.json in project root
• Pin the MCP command to the active Python interpreter
• Install bundled skills into .claude/skills/

Step 7: Browser Configuration

# .env options
BROWSER_TYPE=chromium-headful          # or: chromium-headless, cdp-connect
BROWSER_STREAMING_MODE=vnc             # or: cdp
BROWSER_ACTION_TIMEOUT_MS=5000
MAX_STEPS_PER_RUN=50
VIDEO_PATH=./videos
MAX_SCRAPING_RETRIES=0

# Connect to existing Chrome (local dev)
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://127.0.0.1:9222

Step 8: Credential Management

Skyvern supports stored credentials for automated login:

Step 9: CLI Commands

skyvern quickstart        # Interactive setup wizard
skyvern init              # Setup-only (no service start)
skyvern run all           # Start server + UI
skyvern run server        # Start API server only
skyvern run ui            # Start frontend only
skyvern status            # Check service status
skyvern stop all          # Stop everything
skyvern init browser      # Setup Chrome remote debugging
skyvern browser serve --tunnel  # Start Chrome + tunnel

Guardrail

Do NOT install Skyvern inside the ainish-coder codebase. This codebase is strictly a tool orchestrator. This skill is meant for target repositories where the agent is deployed.

Never use api.skyvern.com or any Skyvern cloud API key. Always self-host with your own LLM provider credentials.

Troubleshooting

1. LLM Configuration Issues

2. Docker Issues

3. SDK / API Issues

4. Diagnostic Steps

1. Verify LLM connectivity: test your provider endpoint directly with curl
2. Check Skyvern logs: docker compose logs skyvern or server stdout
3. Verify .env is complete: compare against .env.example in the repo
4. Fetch latest docs: https://skyvern.com/docs/llms.txt
5. Search codebase: Grep("skyvern") to find deployment/config issues

Examples

• "Automate filling out this insurance form using AI."
• "Extract all product listings from this e-commerce site."
• "Build a workflow to log into a portal, download a report, and email it."
• "Set up Skyvern to monitor a competitor's pricing page daily."
• "Replace our Selenium tests with Skyvern for more resilient automation."
• "Create a workflow that navigates a multi-page signup process."
• "Download all invoices newer than January 1st from a vendor portal."

Guidelines

1. Always self-host — never reference api.skyvern.com or cloud API keys
2. Prefer OpenRouter or OpenAI-compatible for maximum model flexibility
3. Use Skyvern 2.0 engine (Planner→Agent→Validator) for all new tasks
4. Use the Python SDK for programmatic integration; REST API for non-Python
5. Design workflows for reusability — parameterize inputs via workflow parameters
6. Provide clear, specific navigation goals — vague prompts = unreliable automation
7. Handle failures gracefully — check status, implement retries for transient errors
8. Use data_extraction_schema to structure output for downstream processing
9. Always fetch llms.txt before implementing to verify current API surface
10. When troubleshooting, check config_registry.py source for valid LLM_KEY values

Requirements

Self-Hosted (pip)

pip install skyvern  # or: uv pip install skyvern

• Python 3.11.x or 3.12.x (NOT 3.13)
• NodeJS & NPM (for UI)
• LLM provider credentials (OpenRouter, Ollama, or any OpenAI-compatible endpoint)

Self-Hosted (Docker)

• Docker and Docker Compose
• LLM provider credentials in .env
• See https://github.com/Skyvern-AI/skyvern for full setup

Resources