> ## Documentation Index
> Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

## Install

```bash Python theme={null}
# Requires Python 3.11+
pip install skyvern
```

```bash TypeScript theme={null}
# Requires Node.js 18+ (also compatible with Bun, Deno, and Cloudflare Workers)
npm install @skyvern/client
```

> [!NOTE]
>
> `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.

```python Python theme={null}
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())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

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

const result = await skyvern.runTask({
  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](https://app.skyvern.com/settings/). |
| `environment` | `SkyvernEnvironment` | `CLOUD` / `Cloud` | Target environment. See [Environments](#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. |
| `maxRetries` (TypeScript only) | `number` | `2` | Number of times to retry failed requests. The Python constructor has no `max_retries`; pass `RequestOptions(max_retries=...)` per request instead (see [Request options](#request-options)). |
| `headers` | `dict` / `Record<string, string>` | `None` | Additional headers included with every request. |

> [accordion] 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:

```python Python theme={null}
from skyvern.client import SkyvernEnvironment
```

```typescript TypeScript theme={null}
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:

```python Python theme={null}
client = Skyvern(
    api_key="YOUR_API_KEY",
    base_url="https://skyvern.your-company.com",
)
```

```typescript TypeScript theme={null}
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`.

```python theme={null}
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}` |
| `use_in_memory_db` | `bool \| None` | `None` | `True` forces an ephemeral in-memory SQLite database. `False` forces persistent mode (requires `DATABASE_STRING` and `SKYVERN_API_KEY`). `None` auto-detects: persistent if `DATABASE_STRING` is set, otherwise in-memory. |

***

## 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`):

```python Python theme={null}
# 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)
```

```typescript TypeScript theme={null}
// Returns only after the task finishes (up to 30 min by default)
const result = await skyvern.runTask({
  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({
  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:

```python Python theme={null}
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"},
    ),
)
```

```typescript TypeScript theme={null}
// Pass as second argument to any method
const result = await skyvern.runTask(
  {
    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

> [card] [Browser Automation](https://skyvern.com/docs/sdk-reference/browser-automation/browsers.md)
>
> Control browsers with Playwright + AI

> [card] [Tasks](https://skyvern.com/docs/sdk-reference/runs.md)
>
> Run browser automations with `run_task`

> [card] [Agents](https://skyvern.com/docs/sdk-reference/agents.md)
>
> Create and run multi-step automations

> [card] [Error Handling](https://skyvern.com/docs/sdk-reference/error-handling.md)
>
> Handle errors and configure retries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.