> ## 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

<CodeGroup>
  ```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
  ```
</CodeGroup>

<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.
</Note>

***

## Initialize the client

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

<CodeGroup>
  ```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({
    body: {
      prompt: "Get the title of the top post on Hacker News",
      url: "https://news.ycombinator.com",
    },
    waitForCompletion: true,
  });
  console.log(result.output);
  ```
</CodeGroup>

### 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.                                                                              |
| `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.                                                               |

<Accordion title="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. |
</Accordion>

***

## Environments

Three built-in environment URLs:

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

  ```typescript TypeScript theme={null}
  import { SkyvernEnvironment } from "@skyvern/client";
  ```
</CodeGroup>

| 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:

<CodeGroup>
  ```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",
  });
  ```
</CodeGroup>

***

## 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}` |

***

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

<CodeGroup>
  ```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({
    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)
  ```
</CodeGroup>

| 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:

<CodeGroup>
  ```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(
    {
      body: {
        prompt: "Extract data",
        url: "https://example.com",
      },
    },
    {
      timeoutInSeconds: 120,
      maxRetries: 3,
      headers: { "x-custom-header": "value" },
    },
  );
  ```
</CodeGroup>

| 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

<CardGroup cols={2}>
  <Card title="Browser Automation" icon="robot" href="/sdk-reference/browser-automation/launch-cloud-browser">
    Control browsers with Playwright + AI
  </Card>

  <Card title="Tasks" icon="play" href="/sdk-reference/tasks/run-task">
    Run browser automations with `run_task`
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/sdk-reference/workflows/run-workflow">
    Create and run multi-step automations
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/sdk-reference/error-handling">
    Handle errors and configure retries
  </Card>
</CardGroup>