Overview

The Skyvern SDK wraps the REST API in a typed client with built-in browser automation via Playwright.

Install

# Requires Python 3.11+
pip install skyvern

# Requires Node.js 18+ (also compatible with Bun, Deno, and Cloudflare Workers)
npm install @skyvern/client

pip install skyvern is the lightweight SDK for Skyvern Cloud and remote API calls. Embedded local SDK features such as Skyvern.local() and local browser control require pip install "skyvern[local]". Local server and local stdio MCP commands require pip install "skyvern[server]". Guided quickstart and migrations currently require Docker Compose or a source checkout.

Initialize the client

Create a Skyvern instance with your API key. All methods are async.

import asyncio
from skyvern import Skyvern

async def main():
    # All methods are coroutines - wrap in async and use asyncio.run()
    # If inside FastAPI/Django ASGI, await directly without asyncio.run()
    client = Skyvern(api_key="YOUR_API_KEY")

    result = await client.run_task(
        prompt="Get the title of the top post on Hacker News",
        url="https://news.ycombinator.com",
        wait_for_completion=True,
    )
    print(result.output)

asyncio.run(main())

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

// All methods return promises
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });

const result = await skyvern.runTask({
  body: {
    prompt: "Get the title of the top post on Hacker News",
    url: "https://news.ycombinator.com",
  },
  waitForCompletion: true,
});
console.log(result.output);

Constructor parameters

Parameter	Type	Default	Description
`api_key` / `apiKey`	`str` / `string`	-	Required. Your Skyvern API key. Get one at app.skyvern.com/settings.
`environment`	`SkyvernEnvironment`	`CLOUD` / `Cloud`	Target environment. See Environments.
`base_url` / `baseUrl`	`str` / `string`	`None`	Override the API base URL for self-hosted deployments.
`timeout` / `timeoutInSeconds`	`float` / `number`	`None` / `60`	HTTP request timeout in seconds.
`max_retries` / `maxRetries`	`int` / `number`	`None` / `2`	Number of times to retry failed requests.
`headers`	`dict` / `Record<string, string>`	`None`	Additional headers included with every request.

Python-only constructor options

Parameter	Type	Default	Description
`follow_redirects`	`bool`	`True`	Whether to follow HTTP redirects.
`httpx_client`	`httpx.AsyncClient`	`None`	Provide your own httpx client for custom TLS, proxying, or connection pooling.

Environments

Three built-in environment URLs:

from skyvern.client import SkyvernEnvironment

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

Environment	URL	When to use
`CLOUD` / `Cloud`	`https://api.skyvern.com`	Skyvern Cloud (default)
`STAGING` / `Staging`	`https://api-staging.skyvern.com`	Staging environment
`LOCAL` / `Local`	`http://localhost:8000`	Local server started with `skyvern run server`

For a self-hosted instance at a custom URL:

client = Skyvern(
    api_key="YOUR_API_KEY",
    base_url="https://skyvern.your-company.com",
)

const skyvern = new Skyvern({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://skyvern.your-company.com",
});

Local mode

Run Skyvern entirely on your machine - no cloud, no network calls. Skyvern.local() reads your .env file, boots the engine in-process, and connects the client to it. Prerequisite: Install the local extra with pip install "skyvern[local]". For local browser control, also run python -m playwright install chromium.

from skyvern import Skyvern

# Python only. TypeScript requires a running Skyvern server
client = Skyvern.local()

result = await client.run_task(
    prompt="Get the title of the top post",
    url="https://news.ycombinator.com",
    wait_for_completion=True,
)

If you configured headful mode during skyvern quickstart, a Chromium window opens so you can watch the AI work.

Parameter	Type	Default	Description
`llm_config`	`LLMConfig \| LLMRouterConfig \| None`	`None`	Override the LLM. If omitted, uses `LLM_KEY` from `.env`.
`settings`	`dict \| None`	`None`	Override `.env` settings at runtime. Example: `{"MAX_STEPS_PER_RUN": 100}`

Waiting for completion

By default, task and agent runs return immediately after queuing. You get a run ID and need to poll for results yourself. Pass wait_for_completion to have the SDK poll automatically until the run reaches a terminal state (completed, failed, terminated, timed_out, or canceled):

# Returns only after the task finishes (up to 30 min by default)
result = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
    wait_for_completion=True,
    timeout=600,  # give up after 10 minutes
)

# Without wait_for_completion -- returns immediately
task = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
)
print(task.run_id)  # poll with client.get_run(task.run_id)

// Returns only after the task finishes (up to 30 min by default)
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
  waitForCompletion: true,
  timeout: 600, // give up after 10 minutes
});

// Without waitForCompletion -- returns immediately
const task = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
});
console.log(task.run_id); // poll with skyvern.getRun(task.run_id)

Parameter	Type	Default	Description
`wait_for_completion` / `waitForCompletion`	`bool` / `boolean`	`false`	Poll until the run finishes.
`timeout`	`float` / `number`	`1800`	Maximum wait time in seconds.

Supported on task runs, agent runs, and login. In TypeScript, also supported on file downloads.

Request options

Every method accepts per-request overrides for timeout, retries, and headers:

from skyvern.client.core import RequestOptions

result = await client.run_task(
    prompt="Extract data",
    url="https://example.com",
    request_options=RequestOptions(
        timeout_in_seconds=120,
        max_retries=3,
        additional_headers={"x-custom-header": "value"},
    ),
)

// Pass as second argument to any method
const result = await skyvern.runTask(
  {
    body: {
      prompt: "Extract data",
      url: "https://example.com",
    },
  },
  {
    timeoutInSeconds: 120,
    maxRetries: 3,
    headers: { "x-custom-header": "value" },
  },
);

Option	Type	Description
`timeout_in_seconds` / `timeoutInSeconds`	`int` / `number`	HTTP timeout for this request.
`max_retries` / `maxRetries`	`int` / `number`	Retry count for this request.
`additional_headers` / `headers`	`dict` / `Record<string, string>`	Extra headers for this request.
`additional_query_parameters`	`dict`	Extra query parameters (Python only).
`additional_body_parameters`	`dict`	Extra body parameters (Python only).
`abortSignal`	`AbortSignal`	Signal to abort the request (TypeScript only).
`apiKey`	`string`	Override the API key for this request (TypeScript only).

These override the client-level defaults for that single call only.

Next steps

Browser Automation

Control browsers with Playwright + AI

Tasks

Run browser automations with run_task

Workflows

Create and run multi-step automations

Error Handling

Handle errors and configure retries

SDK

Browser Automation

Tasks

Agents

Browser Sessions

Browser Profiles

Credentials

Helpers

Install

Initialize the client

Constructor parameters

Environments

Local mode

Waiting for completion

Request options

Next steps

Browser Automation

Tasks

Workflows

Error Handling

​Install

​Initialize the client

​Constructor parameters

​Environments

​Local mode

​Waiting for completion

​Request options

​Next steps

Browser Automation

Tasks

Workflows

Error Handling

Install

Initialize the client

Constructor parameters

Environments

Local mode

Waiting for completion

Request options

Next steps