Skip to main content
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
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())

​
Constructor parameters

ParameterTypeDefaultDescription
api_key / apiKeystr / string-Required. Your Skyvern API key. Get one at app.skyvern.com/settings.
environmentSkyvernEnvironmentCLOUD / CloudTarget environment. See Environments.
base_url / baseUrlstr / stringNoneOverride the API base URL for self-hosted deployments.
timeout / timeoutInSecondsfloat / numberNone / 60HTTP request timeout in seconds.
max_retries / maxRetriesint / numberNone / 2Number of times to retry failed requests.
headersdict / Record<string, string>NoneAdditional headers included with every request.
ParameterTypeDefaultDescription
follow_redirectsboolTrueWhether to follow HTTP redirects.
httpx_clienthttpx.AsyncClientNoneProvide your own httpx client for custom TLS, proxying, or connection pooling.

​
Environments

Three built-in environment URLs: 
from skyvern.client import SkyvernEnvironment
EnvironmentURLWhen to use
CLOUD / Cloudhttps://api.skyvern.comSkyvern Cloud (default)
STAGING / Staginghttps://api-staging.skyvern.comStaging environment
LOCAL / Localhttp://localhost:8000Local 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",
)

​
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.
ParameterTypeDefaultDescription
llm_configLLMConfig | LLMRouterConfig | NoneNoneOverride the LLM. If omitted, uses LLM_KEY from .env.
settingsdict | NoneNoneOverride .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)
ParameterTypeDefaultDescription
wait_for_completion / waitForCompletionbool / booleanfalsePoll until the run finishes.
timeoutfloat / number1800Maximum 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"},
    ),
)
OptionTypeDescription
timeout_in_seconds / timeoutInSecondsint / numberHTTP timeout for this request.
max_retries / maxRetriesint / numberRetry count for this request.
additional_headers / headersdict / Record<string, string>Extra headers for this request.
additional_query_parametersdictExtra query parameters (Python only).
additional_body_parametersdictExtra body parameters (Python only).
abortSignalAbortSignalSignal to abort the request (TypeScript only).
apiKeystringOverride 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