Skip to main content
By the end of this guide, you’ll scrape the top post from Hacker News using Skyvern’s AI agent.
Prefer a visual interface? Try Skyvern Cloud — no code required.

​
Installation Options

Skyvern can be run locally or in the cloud. Choose your preferred setup:

​
Prerequisites

For Windows users, also install:
  • Rust
  • VS Code with C++ dev tools and Windows SDK

​
Install Skyvern

pip install skyvern

​
Run Skyvern

skyvern quickstart
If you already have a database you want to use, pass a custom connection string:
skyvern quickstart --database-string "postgresql+psycopg://user:password@localhost:5432/skyvern"

​
Your First Task

1

Get your API key

Sign up at app.skyvern.com and go to Settings to copy your API key.When you make API calls, Skyvern spins up a cloud browser, executes your task with AI, and returns the results.
2

Install the SDK

pip install skyvern
3

Run your first task

Let’s scrape the title of the #1 post on Hacker News. You only need two parameters:
  • prompt — Natural language instructions for what the AI should do
  • url — The starting page
import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    print(f"Run ID: {result.run_id}")
    print(f"Status: {result.status}")

asyncio.run(main())
4

Check the status

Since tasks run asynchronously, poll every 5 seconds until the task completes:
import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    run_id = result.run_id
    print(f"Task started: {run_id}")

    while True:
        run = await client.get_run(run_id)
        print(f"Status: {run.status}")

        if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
            break

        await asyncio.sleep(5)

    print(f"Final status: {run.status}")
    print(f"Output: {run.output}")

asyncio.run(main())
Run states:
  • created — Task initialized, not yet queued
  • queued — Waiting for an available browser
  • running — AI is navigating and executing
  • completed — Task finished successfully
  • failed — Task encountered an error
  • terminated — Task was manually stopped
  • timed_out — Task exceeded time limit
  • canceled — Task was cancelled before starting
5

View your results

When the task completes, you’ll get a response like this:
{
  "run_id": "tsk_v2_486305187432193504",
  "status": "completed",
  "output": {
    "top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
  },
  "downloaded_files": [],
  "recording_url": "https://skyvern-artifacts.s3.amazonaws.com/...",
  "screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/..."],
  "app_url": "https://app.skyvern.com/runs/wr_486305187432193510",
  "step_count": 2,
  "run_type": "task_v2"
}
The output contains whatever data the AI extracted based on your prompt. The app_url links to the Cloud UI where you can view the full run details and recording.

​
SDK Usage Examples

Skyvern is a Playwright extension that adds AI-powered browser automation. It gives you the full power of Playwright with additional AI capabilities.

​
AI-Powered Page Commands

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

​
Core AI Commands

CommandDescription
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

​
Extract Structured Data

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"
            }
        }
    }
)

​
Run Locally

Run Skyvern with a browser on your own machine for development, debugging, or automating internal tools.
1

Set up local Skyvern

skyvern init
This interactive wizard will:
  1. Set up your database (detects local PostgreSQL or uses Docker)
  2. Configure your LLM provider
  3. Choose browser mode (headless, headful, or connect to existing Chrome)
  4. Generate local API credentials
  5. Download the Chromium browser
2

Start the local server

skyvern run server
3

Run a task locally

import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(
        base_url="http://localhost:8000",
        api_key=os.getenv("SKYVERN_API_KEY")
    )

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    print(f"Run ID: {result.run_id}")

asyncio.run(main())
A browser window will open on your machine (if you chose headful mode). Recordings and logs are saved in the directory where you started the server.

​
Helpful Commands

# Launch the Skyvern Server
skyvern run server

# Launch the Skyvern UI
skyvern run ui

# Launch both server and UI
skyvern run all

# 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
skyvern stop server

​
Next Steps

Core Concepts

Learn about Tasks, Workflows, Browser Sessions, and more

Extract Structured Data

Define a schema to get typed JSON output from your automations

Handle Logins

Store credentials securely for sites that require authentication

Build Workflows

Chain multiple steps together for complex automations

Build docs developers (and LLMs) love

Get started for freeTalk to us