同步完整源码 - 2026-05-24
This commit is contained in:
@@ -0,0 +1,860 @@
|
||||
---
|
||||
title: Actions Reference
|
||||
subtitle: Every page action and agent method
|
||||
description: Reference for all page actions (act, extract, validate, prompt, click, fill, select_option) and agent methods (login, run_task, download_files, run_workflow) with parameters and return types.
|
||||
slug: developers/browser-automations/actions-reference
|
||||
keywords:
|
||||
- act
|
||||
- extract
|
||||
- validate
|
||||
- prompt
|
||||
- click
|
||||
- fill
|
||||
- select_option
|
||||
- agent.login
|
||||
- agent.run_task
|
||||
- agent.download_files
|
||||
- agent.run_workflow
|
||||
- fill_form
|
||||
- locator
|
||||
- frame_switch
|
||||
---
|
||||
|
||||
Browser automations are built in code using three layers: Page (AI-enhanced Playwright), Agent (multi-step AI goals), and Browser (cloud Chromium instance). This page lists every operation available on a Page or through an Agent. For the full SDK documentation with all parameter options, see the [SDK Reference](/sdk-reference/browser-automation/act).
|
||||
|
||||
If you're building automations visually instead, see [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for the equivalent operations in the Cloud UI workflow editor.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
### Page actions
|
||||
|
||||
| Action | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`act`](#act) | Perform any action from a natural-language prompt | `None` |
|
||||
| [`extract`](#extract) | Pull structured data from the page | `dict`, `list`, `str`, or `None` |
|
||||
| [`validate`](#validate) | Assert a condition about the page | `bool` |
|
||||
| [`prompt`](#prompt) | Ask the LLM a question about the page | `dict`, `list`, `str`, or `None` |
|
||||
| [`click`](#click) | Click an element (selector, AI, or both) | `str \| None` |
|
||||
| [`fill`](#fill) | Fill an input field (selector, AI, or both) | `str` |
|
||||
| [`select_option`](#select_option) | Select a dropdown option (selector, AI, or both) | `str \| None` |
|
||||
| [`type`](#type) | Type text character-by-character (Python only) | `str` |
|
||||
| [`hover`](#hover) | Move mouse over an element (Python only) | `str` |
|
||||
| [`scroll`](#scroll) | Scroll the page by pixel offset (Python only) | `None` |
|
||||
| [`upload_file`](#upload_file) | Upload files to a file input (Python only) | `str` |
|
||||
| [`locator`](#locator) | Locate an element with AI, returns a chainable Locator (Python only) | `Locator` |
|
||||
|
||||
### Agent methods
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`agent.login`](#agentlogin) | Authenticate with stored credentials | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
| [`agent.run_task`](#agentrun_task) | Run a multi-step AI task on the current page | [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) |
|
||||
| [`agent.download_files`](#agentdownload_files) | Navigate and download files | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
| [`agent.run_workflow`](#agentrun_workflow) | Run a Cloud UI workflow on the current page | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
|
||||
### Form automation (Python only)
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`fill_form`](#fill_form) | AI-powered single-page form fill | `None` |
|
||||
| [`fill_multipage_form`](#fill_multipage_form) | Form fill across multiple pages | `int` (pages filled) |
|
||||
| [`fill_from_mapping`](#fill_from_mapping) | Fill fields by index-to-value mapping | `None` |
|
||||
| [`extract_form_fields`](#extract_form_fields) | Extract all form field metadata | `list[dict]` |
|
||||
| [`validate_mapping`](#validate_mapping) | Check if a field mapping is valid | `bool` |
|
||||
| [`fill_autocomplete`](#fill_autocomplete) | Fill input with typeahead handling | `str` |
|
||||
|
||||
### iframe management (Python only)
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`frame_switch`](#frame_switch) | Switch context to an iframe | `dict` |
|
||||
| [`frame_main`](#frame_main) | Switch back to the main frame | `dict` |
|
||||
| [`frame_list`](#frame_list) | List all frames on the page | `list[dict]` |
|
||||
|
||||
---
|
||||
|
||||
## Page actions
|
||||
|
||||
### act
|
||||
|
||||
Perform any action described in natural language.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.act("Click the login button")
|
||||
await page.act("Scroll down to the pricing section")
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.act("Click the login button")
|
||||
await page.act("Scroll down to the pricing section")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What action to perform |
|
||||
| `skip_refresh` | `bool` | No | Skip page refresh before acting |
|
||||
| `use_economy_tree` | `bool` | No | Use a smaller DOM tree for faster processing |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [act](/sdk-reference/browser-automation/act)
|
||||
|
||||
---
|
||||
|
||||
### extract
|
||||
|
||||
Pull structured data from the visible page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
data = await page.extract(
|
||||
"Extract all product names and prices",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"price": {"type": "number"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const data = await page.extract({
|
||||
prompt: "Extract all product names and prices",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
name: { type: "string" },
|
||||
price: { type: "number" },
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What to extract |
|
||||
| `schema` | `dict \| list \| str` | No | JSON Schema for typed output |
|
||||
| `error_code_mapping` | `dict` | No | Map custom error codes |
|
||||
|
||||
**Returns:** `dict`, `list`, `str`, or `None`
|
||||
|
||||
**SDK reference:** [extract](/sdk-reference/browser-automation/extract)
|
||||
|
||||
---
|
||||
|
||||
### validate
|
||||
|
||||
Assert a condition about the current page state.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
is_logged_in = await page.validate("The user is logged in")
|
||||
```
|
||||
|
||||
```typescript
|
||||
const isLoggedIn = await page.validate("The user is logged in")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Condition to check |
|
||||
| `model` | `dict` | No | Override LLM model config |
|
||||
|
||||
**Returns:** `bool`
|
||||
|
||||
**SDK reference:** [validate](/sdk-reference/browser-automation/validate)
|
||||
|
||||
---
|
||||
|
||||
### prompt
|
||||
|
||||
Ask the LLM a question about the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.prompt(
|
||||
"How many items are in the navigation menu?",
|
||||
schema={"count": {"type": "integer"}}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.prompt(
|
||||
"How many items are in the navigation menu?",
|
||||
{ schema: { count: { type: "integer" } } }
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Question to ask |
|
||||
| `schema` | `dict` | No | JSON Schema for structured response |
|
||||
| `model` | `dict` | No | Override LLM model config |
|
||||
|
||||
**Returns:** `dict`, `list`, `str`, or `None`. Without a `schema`, returns a `dict` of the form `{"llm_response": "..."}` (TypeScript: `{ llmResponse: "..." }`). With a `schema`, returns data shaped to your schema.
|
||||
|
||||
**SDK reference:** [prompt](/sdk-reference/browser-automation/prompt)
|
||||
|
||||
---
|
||||
|
||||
### click
|
||||
|
||||
Click an element using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.click("#submit-button") # selector
|
||||
await page.click(prompt="Click the 'Submit' button") # AI
|
||||
await page.click("#submit-button", prompt="Click the 'Submit' button") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.click("#submit-button") // selector
|
||||
await page.click({ prompt: "Click the 'Submit' button" }) // AI
|
||||
await page.click("#submit-button", { prompt: "Click the 'Submit' button" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
|
||||
**Returns:** `str \| None` (resolved selector)
|
||||
|
||||
**SDK reference:** [click](/sdk-reference/browser-automation/click)
|
||||
|
||||
---
|
||||
|
||||
### fill
|
||||
|
||||
Fill an input field using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.fill("#email", value="user@example.com") # selector
|
||||
await page.fill(prompt="Fill 'user@example.com' in the email field") # AI
|
||||
await page.fill("#email", value="user@example.com", prompt="Fill email") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.fill("#email", "user@example.com") // selector
|
||||
await page.fill({ prompt: "Fill 'user@example.com' in the email field" }) // AI
|
||||
await page.fill("#email", "user@example.com", { prompt: "Fill email" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `value` | `str` | No | Value to fill |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
| `totp_identifier` | `str` | No | TOTP identifier for 2FA fields |
|
||||
| `totp_url` | `str` | No | TOTP URL |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [fill](/sdk-reference/browser-automation/fill)
|
||||
|
||||
---
|
||||
|
||||
### select_option
|
||||
|
||||
Select a dropdown option using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.select_option("#country", value="us") # selector
|
||||
await page.select_option(prompt="Select 'United States' from the country dropdown") # AI
|
||||
await page.select_option("#country", value="us", prompt="Select United States") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.selectOption("#country", { value: "us" }) // selector
|
||||
await page.selectOption({ prompt: "Select 'United States' from the country dropdown" }) // AI
|
||||
await page.selectOption("#country", { value: "us", prompt: "Select United States" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `value` | `str \| list[str]` | No | Option value(s) to select |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
|
||||
**Returns:** `str | None` (resolved selector)
|
||||
|
||||
**SDK reference:** [select_option](/sdk-reference/browser-automation/select-option)
|
||||
|
||||
---
|
||||
|
||||
### type
|
||||
|
||||
Type text character-by-character. Unlike `fill`, this triggers keystroke events for each character, so use it for fields that react to individual key presses (search autocomplete, OTP inputs). Python only.
|
||||
|
||||
```python
|
||||
# Character-by-character input via selector
|
||||
await page.type("#search", value="wireless headphones")
|
||||
|
||||
# AI-powered type
|
||||
await page.type(prompt="Type 'hello' into the search box")
|
||||
|
||||
# Selector with AI fallback
|
||||
await page.type("#search", value="query text", prompt="Type into the search field")
|
||||
|
||||
# TOTP input from a stored secret
|
||||
await page.type("#otp", totp_identifier="my-app")
|
||||
|
||||
# TOTP generated on the fly from an otpauth URI
|
||||
await page.type("#otp", totp_url="otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector for the input field |
|
||||
| `value` | `str` | No | Text to type character-by-character |
|
||||
| `prompt` | `str` | No | Natural-language description of the target field |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `totp_identifier` | `str` | No | Identifier for a stored TOTP secret |
|
||||
| `totp_url` | `str` | No | `otpauth://` URI to generate a one-time password on the fly |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [type](/sdk-reference/browser-automation/type)
|
||||
|
||||
---
|
||||
|
||||
### hover
|
||||
|
||||
Move the mouse over an element. Python only.
|
||||
|
||||
```python
|
||||
# Simple hover
|
||||
await page.hover("#menu-item")
|
||||
|
||||
# Hover with a hold duration (useful for tooltip reveals)
|
||||
await page.hover("#tooltip-trigger", hold_seconds=1.5)
|
||||
|
||||
# Hover with intention logging for debugging
|
||||
await page.hover("#menu-item", intention="Reveal the main menu dropdown")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | Yes | CSS or XPath selector for the target element |
|
||||
| `timeout` | `float` | No | Max wait time in milliseconds for the element. Defaults to `BROWSER_ACTION_TIMEOUT_MS` |
|
||||
| `hold_seconds` | `float` | No | How long to hold the hover, in seconds. Default `0.0` |
|
||||
| `intention` | `str` | No | Description of the hover intent, used for logging |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [hover](/sdk-reference/browser-automation/hover)
|
||||
|
||||
---
|
||||
|
||||
### scroll
|
||||
|
||||
Scroll the page by a pixel offset along the x and y axes. Python only.
|
||||
|
||||
```python
|
||||
await page.scroll(0, 500) # Scroll down 500px
|
||||
await page.scroll(0, -300) # Scroll up 300px
|
||||
await page.scroll(200, 0) # Scroll right 200px
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `scroll_x` | `int` | Yes | Horizontal scroll offset in pixels. Positive values scroll right |
|
||||
| `scroll_y` | `int` | Yes | Vertical scroll offset in pixels. Positive values scroll down |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [scroll](/sdk-reference/browser-automation/scroll)
|
||||
|
||||
---
|
||||
|
||||
### upload_file
|
||||
|
||||
Upload one or more files to a file input. Pass a selector for direct Playwright behavior, a prompt for AI-powered file input detection, or both. Python only.
|
||||
|
||||
```python
|
||||
# Direct selector
|
||||
await page.upload_file("#file-input", files="/path/to/file.pdf")
|
||||
|
||||
# Multiple files
|
||||
await page.upload_file("#file-input", files=["/path/to/file1.pdf", "/path/to/file2.pdf"])
|
||||
|
||||
# AI-powered file input detection (no selector needed)
|
||||
await page.upload_file(prompt="Upload the resume to the file input")
|
||||
|
||||
# Selector with AI fallback: try the selector first, use AI if it fails
|
||||
await page.upload_file(
|
||||
"#file-input",
|
||||
files="/path/to/file.pdf",
|
||||
prompt="Upload the resume to the file input",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector for the file input |
|
||||
| `files` | `str \| list[str]` | No | File path or list of file paths to upload |
|
||||
| `prompt` | `str` | No | Natural-language description of the file input to target |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [upload_file](/sdk-reference/browser-automation/upload-file)
|
||||
|
||||
---
|
||||
|
||||
### locator
|
||||
|
||||
Locate an element using a CSS/XPath selector, an AI prompt, or both. When called with a `prompt`, returns an `AILocator`, a lazy Playwright `Locator` that resolves the element via AI on first use. Python only.
|
||||
|
||||
```python
|
||||
# AI-powered: pass a natural-language prompt
|
||||
locator = page.locator(prompt="the submit button")
|
||||
await locator.click()
|
||||
|
||||
# Full Playwright chaining works
|
||||
text = await page.locator(prompt="the error message").text_content()
|
||||
|
||||
# Standard Playwright selector (no AI, identical to vanilla Playwright)
|
||||
locator = page.locator("#submit-btn")
|
||||
await locator.click()
|
||||
|
||||
# Selector with AI fallback: try the selector first, use AI if it fails
|
||||
locator = page.locator("#submit-btn", prompt="the submit button")
|
||||
await locator.click()
|
||||
```
|
||||
|
||||
<Note>
|
||||
When called with only a `selector` (no `prompt`), `page.locator(selector)` behaves exactly like the standard Playwright `page.locator(selector)`. No AI is involved.
|
||||
</Note>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector passed to Playwright's built-in `locator()` |
|
||||
| `prompt` | `str` | No | Natural-language description of the element. When provided, returns an `AILocator` that resolves via AI |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `**kwargs` | | No | Additional keyword arguments forwarded to Playwright's `locator()` |
|
||||
|
||||
**Returns:** `Locator` (standard Playwright `Locator` when only a selector is given, or `AILocator` when a prompt is provided)
|
||||
|
||||
#### AILocator methods
|
||||
|
||||
When `prompt` is provided, the returned `AILocator` supports all standard Playwright `Locator` methods:
|
||||
|
||||
- **Actions:** `click()`, `fill()`, `type()`, `select_option()`, `check()`, `uncheck()`, `clear()`, `hover()`, `focus()`, `press()`
|
||||
- **Queries:** `text_content()`, `inner_text()`, `inner_html()`, `get_attribute()`, `input_value()`, `count()`
|
||||
- **State:** `is_visible()`, `is_hidden()`, `is_enabled()`, `is_disabled()`, `is_editable()`, `is_checked()`
|
||||
- **Chaining:** `first()`, `last()`, `nth()`, `filter()`, `locator()`, `get_by_text()`, `get_by_role()`, `get_by_label()`, `get_by_placeholder()`
|
||||
- **Utilities:** `wait_for()`, `screenshot()`, `playwright_locator` (access raw `Locator`)
|
||||
|
||||
**SDK reference:** [locator](/sdk-reference/browser-automation/locator)
|
||||
|
||||
---
|
||||
|
||||
## Agent methods
|
||||
|
||||
All agent methods return either a [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) (for `agent.run_task`) or a [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) (for `agent.login`, `agent.download_files`, `agent.run_workflow`). Follow the links for the full field list.
|
||||
|
||||
### agent.login
|
||||
|
||||
Authenticate with stored credentials. Handles multi-page login flows, CAPTCHAs, and 2FA.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.agent.login(
|
||||
credential_type="skyvern",
|
||||
credential_id="cred_123"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.agent.login("skyvern", {
|
||||
credentialId: "cred_123"
|
||||
})
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `credential_type` | `CredentialType` | Yes | `skyvern`, `bitwarden`, `onepassword`, or `azure_vault` |
|
||||
| `credential_id` | `str` | No | Credential ID (required for `skyvern` type) |
|
||||
| `url` | `str` | No | Login page URL |
|
||||
| `prompt` | `str` | No | Additional login instructions |
|
||||
| `timeout` | `float` | No | Max wait time in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.login](/sdk-reference/browser-automation/agent-login)
|
||||
|
||||
---
|
||||
|
||||
### agent.run_task
|
||||
|
||||
Run a multi-step AI task on the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.run_task(
|
||||
"Go to the billing page and download the latest invoice",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
)
|
||||
print(result.output)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.runTask(
|
||||
"Go to the billing page and download the latest invoice",
|
||||
{
|
||||
dataExtractionSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
console.log(result.output)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Multi-step goal description |
|
||||
| `data_extraction_schema` | `dict \| str` | No | JSON Schema for structured output. See [Extract Structured Data](/developers/browser-automations/extract-structured-data). |
|
||||
| `max_steps` | `int` | No | Cap AI steps. The run terminates with `timed_out` if hit. Controls cost; each step is one AI decision + action cycle. |
|
||||
| `engine` | `RunEngine` | No | AI engine. Defaults to `skyvern-1.0` in the SDK for backward compatibility. Pass `skyvern-2.0` for the latest model (also the Cloud UI default). Other options: `openai-cua`, `anthropic-cua`, `ui-tars`. |
|
||||
| `model` | `dict` / `Record<string, unknown>` | No | Override LLM model configuration |
|
||||
| `url` | `str` / `string` | No | URL to navigate to (defaults to current page URL) |
|
||||
| `webhook_url` | `str` / `string` | No | Callback URL. Skyvern POSTs the full run result on completion or failure. See [Webhooks](/developers/going-to-production/webhooks). |
|
||||
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP. See [Handle 2FA](/developers/credentials/handle-2fa). |
|
||||
| `totp_url` | `str` / `string` | No | Endpoint Skyvern calls to pull TOTP codes. See [Handle 2FA](/developers/credentials/handle-2fa). |
|
||||
| `title` | `str` / `string` | No | Display name for this run |
|
||||
| `error_code_mapping` | `dict` / `Record<string, string>` | No | Map custom error codes to conditions. Keys are your error codes, values describe when to trigger them. If matched, `output` contains `{"error": "your_code"}`. |
|
||||
| `user_agent` | `str` / `string` | No | Custom User-Agent header for the browser |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse)
|
||||
|
||||
**SDK reference:** [agent.run_task](/sdk-reference/browser-automation/agent-run-task)
|
||||
|
||||
---
|
||||
|
||||
### agent.download_files
|
||||
|
||||
Navigate and download files from the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.download_files(
|
||||
"Download the latest invoice PDF",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the latest invoice PDF",
|
||||
{
|
||||
downloadSuffix: ".pdf",
|
||||
downloadTimeout: 30,
|
||||
},
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What to download |
|
||||
| `download_suffix` | `str` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). Not a validator; mismatched extensions don't fail the run. |
|
||||
| `download_timeout` | `float` | No | Soft hint (seconds) for how long to wait for a download. The overall `timeout` is what actually fails the run. |
|
||||
| `max_steps_per_run` | `int` | No | Cap AI steps |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.download_files](/sdk-reference/browser-automation/agent-download-files)
|
||||
|
||||
---
|
||||
|
||||
### agent.run_workflow
|
||||
|
||||
Run a Cloud UI workflow on the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.run_workflow(
|
||||
"wpid_monthly_report",
|
||||
parameters={"month": "2025-03"}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.runWorkflow(
|
||||
"wpid_monthly_report",
|
||||
{ parameters: { month: "2025-03" } }
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `workflow_id` | `str` | Yes | Workflow permanent ID |
|
||||
| `parameters` | `dict` | No | Workflow input parameters |
|
||||
| `template` | `bool` | No | Run a template workflow |
|
||||
| `title` | `str` / `string` | No | Display name for this run |
|
||||
| `webhook_url` | `str` / `string` | No | Callback URL for run completion. See [Webhooks](/developers/going-to-production/webhooks). |
|
||||
| `totp_url` | `str` / `string` | No | Endpoint for pulling TOTP codes |
|
||||
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.run_workflow](/sdk-reference/browser-automation/agent-run-workflow)
|
||||
|
||||
---
|
||||
|
||||
## Form automation (Python only)
|
||||
|
||||
### fill_form
|
||||
|
||||
Fill a single-page form using AI. Pass a `data` dict describing the values to fill.
|
||||
|
||||
```python
|
||||
# Simple form fill
|
||||
await page.fill_form(
|
||||
data={"name": "John Doe", "email": "john@example.com", "role": "Engineer"},
|
||||
)
|
||||
|
||||
# With a custom prompt to guide the AI
|
||||
await page.fill_form(
|
||||
data={"name": "John Doe", "email": "john@example.com"},
|
||||
prompt="Fill out the registration form with the provided user details",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill |
|
||||
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [fill_form](/sdk-reference/browser-automation/fill-form)
|
||||
|
||||
---
|
||||
|
||||
### fill_multipage_form
|
||||
|
||||
Fill a form that spans multiple pages, handling page transitions automatically.
|
||||
|
||||
```python
|
||||
pages_filled = await page.fill_multipage_form(
|
||||
data={"name": "John Doe", "email": "john@example.com", "address": "123 Main St"},
|
||||
max_pages=5,
|
||||
)
|
||||
print(f"Filled {pages_filled} pages")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill across all pages |
|
||||
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
|
||||
| `next_button` | `str` | No | Selector or description of the button to advance to the next page |
|
||||
| `max_pages` | `int` | No | Maximum number of pages to fill. Defaults to `10` |
|
||||
| `timeout_seconds` | `float` | No | Timeout in seconds for the entire operation. Defaults to `300` |
|
||||
|
||||
**Returns:** `int` (the number of pages filled)
|
||||
|
||||
**SDK reference:** [fill_multipage_form](/sdk-reference/browser-automation/fill-multipage-form)
|
||||
|
||||
---
|
||||
|
||||
### fill_from_mapping
|
||||
|
||||
Fill form fields using an explicit index-based mapping produced by `extract_form_fields`. Use this when you need precise control over which field gets which value.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
await page.fill_from_mapping(
|
||||
form_fields=fields,
|
||||
mapping={0: "John", 1: "Doe", 2: "john@example.com"}, # keys are field indices
|
||||
data={"name": "John Doe"}, # optional context
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
|
||||
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to fill |
|
||||
| `data` | `dict[str, Any] \| None` | No | Optional source data for context. Defaults to `None` |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [fill_from_mapping](/sdk-reference/browser-automation/fill-from-mapping)
|
||||
|
||||
---
|
||||
|
||||
### extract_form_fields
|
||||
|
||||
Extract all form fields with metadata from the current page. Use the output to drive `fill_from_mapping` or `validate_mapping`.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
# Returns a list of dicts with field name, type, options, and other metadata:
|
||||
# [{"name": "First Name", "type": "text", "index": 0, ...}, ...]
|
||||
```
|
||||
|
||||
**Returns:** `list[dict[str, Any]]` where each dict contains field name, type, options, and other metadata.
|
||||
|
||||
**SDK reference:** [extract_form_fields](/sdk-reference/browser-automation/extract-form-fields)
|
||||
|
||||
---
|
||||
|
||||
### validate_mapping
|
||||
|
||||
Check if a field mapping is correct for the current form.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
is_valid = await page.validate_mapping(
|
||||
form_fields=fields,
|
||||
mapping={0: "John", 1: "Doe"},
|
||||
prompt="Validate the name fields are filled correctly",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
|
||||
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to validate |
|
||||
| `prompt` | `str` | Yes | Instruction describing what to validate |
|
||||
|
||||
**Returns:** `bool` (`True` if the mapping is valid, `False` otherwise)
|
||||
|
||||
**SDK reference:** [validate_mapping](/sdk-reference/browser-automation/validate-mapping)
|
||||
|
||||
---
|
||||
|
||||
### fill_autocomplete
|
||||
|
||||
Fill an input that has autocomplete/typeahead behavior. Types the value, waits for suggestions, then clicks the matching option.
|
||||
|
||||
```python
|
||||
# Direct selector
|
||||
await page.fill_autocomplete(
|
||||
selector="#city",
|
||||
value="San Francisco",
|
||||
option_selector=".autocomplete-option",
|
||||
wait_seconds=1.5,
|
||||
)
|
||||
|
||||
# AI-powered
|
||||
await page.fill_autocomplete(prompt="Fill 'San Francisco' in the city autocomplete")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector for the input field |
|
||||
| `value` | `str` | No | The text value to type into the field |
|
||||
| `prompt` | `str` | No | Natural-language description of the field and value |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `option_selector` | `str` | No | CSS selector for the autocomplete dropdown options |
|
||||
| `wait_seconds` | `float` | No | Seconds to wait for the dropdown to appear. Default `1.5` |
|
||||
| `**kwargs` | | No | Standard Playwright fill options (e.g., `timeout`, `force`) |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [fill_autocomplete](/sdk-reference/browser-automation/fill-autocomplete)
|
||||
|
||||
---
|
||||
|
||||
## iframe management (Python only)
|
||||
|
||||
### frame_switch
|
||||
|
||||
Switch the working context to an iframe. Exactly one of `selector`, `name`, or `index` must be provided.
|
||||
|
||||
```python
|
||||
# By CSS selector
|
||||
await page.frame_switch(selector="#payment-iframe")
|
||||
|
||||
# By frame name
|
||||
await page.frame_switch(name="checkout")
|
||||
|
||||
# By zero-based index
|
||||
await page.frame_switch(index=0)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector for the iframe element |
|
||||
| `name` | `str` | No | The `name` attribute of the iframe |
|
||||
| `index` | `int` | No | Zero-based index of the iframe on the page |
|
||||
|
||||
<Note>
|
||||
Exactly one of `selector`, `name`, or `index` must be provided.
|
||||
</Note>
|
||||
|
||||
**Returns:** `dict[str, Any]` (frame metadata for the switched-to iframe)
|
||||
|
||||
**SDK reference:** [frame_switch](/sdk-reference/browser-automation/frame-switch)
|
||||
|
||||
---
|
||||
|
||||
### frame_main
|
||||
|
||||
Switch back to the main page frame after working inside an iframe.
|
||||
|
||||
```python
|
||||
page.frame_main()
|
||||
```
|
||||
|
||||
**Returns:** `dict[str, str]`
|
||||
|
||||
**SDK reference:** [frame_main](/sdk-reference/browser-automation/frame-main)
|
||||
|
||||
---
|
||||
|
||||
### frame_list
|
||||
|
||||
List all frames on the current page with metadata.
|
||||
|
||||
```python
|
||||
frames = await page.frame_list()
|
||||
# [{"name": "checkout", "url": "...", "index": 0}, ...]
|
||||
```
|
||||
|
||||
**Returns:** `list[dict[str, Any]]` (metadata for each frame on the page)
|
||||
|
||||
**SDK reference:** [frame_list](/sdk-reference/browser-automation/frame-list)
|
||||
@@ -0,0 +1,717 @@
|
||||
---
|
||||
title: Extract Structured Data
|
||||
subtitle: Get consistent, typed output from your automations
|
||||
description: Define JSON Schema extraction schemas for Skyvern tasks to get consistent, typed output. Build schemas for single objects or arrays of items with the interactive schema builder.
|
||||
slug: developers/browser-automations/extract-structured-data
|
||||
keywords:
|
||||
- JSON Schema
|
||||
- extraction schema
|
||||
- typed output
|
||||
- schema builder
|
||||
- array
|
||||
- object
|
||||
- string
|
||||
- number
|
||||
- boolean
|
||||
---
|
||||
|
||||
import { FIELD_TYPES, SchemaBuilder } from "/snippets/schema-builder.mdx";
|
||||
|
||||
When building browser automations in code, you can extract structured data from any page using `page.extract` with a JSON schema, or by passing a `data_extraction_schema` to `page.agent.run_task`. By default, Skyvern returns extracted data in whatever format makes sense for the action. Pass a schema to enforce a specific shape using [JSON Schema](https://json-schema.org/).
|
||||
|
||||
If you're using the Cloud UI workflow editor instead, extraction works through the Extract block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for setup.
|
||||
|
||||
---
|
||||
|
||||
## Define a schema
|
||||
|
||||
Pass a JSON Schema object to `page.extract` via the `schema` parameter, or to `run_task` via `data_extraction_schema`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="page.extract (browser automation)">
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
data = await page.extract(
|
||||
"Get the title of the top post",
|
||||
schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const data = await page.extract({
|
||||
prompt: "Get the title of the top post",
|
||||
schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "The title of the top post",
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
</Tab>
|
||||
<Tab title="run_task">
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the title of the top post",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the title of the top post",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "The title of the top post",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the title of the top post",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
The `description` field in each property helps Skyvern understand what data to extract. Be specific.
|
||||
|
||||
<Warning>
|
||||
`description` fields drive extraction quality. Vague descriptions like "the data" produce vague results. Be specific: "The product price in USD, without currency symbol."
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Schema format
|
||||
|
||||
Skyvern uses standard JSON Schema. Common types:
|
||||
|
||||
| Type | JSON Schema | Example value |
|
||||
|------|-------------|---------------|
|
||||
| String | `{"type": "string"}` | `"Hello world"` |
|
||||
| Number | `{"type": "number"}` | `19.99` |
|
||||
| Integer | `{"type": "integer"}` | `42` |
|
||||
| Boolean | `{"type": "boolean"}` | `true` |
|
||||
| Array | `{"type": "array", "items": {...}}` | `[1, 2, 3]` |
|
||||
| Object | `{"type": "object", "properties": {...}}` | `{"key": "value"}` |
|
||||
|
||||
<Note>
|
||||
A schema doesn't guarantee all fields are populated. If the data isn't on the page, fields return `null`. Design your code to handle missing values.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Build your schema
|
||||
|
||||
Use the interactive builder to generate a schema, then copy it into your code.
|
||||
|
||||
<SchemaBuilder />
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Single value
|
||||
|
||||
Extract one piece of information, such as the current price of Bitcoin:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the current Bitcoin price in USD",
|
||||
url="https://coinmarketcap.com/currencies/bitcoin/",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"price": {
|
||||
"type": "number",
|
||||
"description": "Current Bitcoin price in USD"
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the current Bitcoin price in USD",
|
||||
url: "https://coinmarketcap.com/currencies/bitcoin/",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
price: {
|
||||
type: "number",
|
||||
description: "Current Bitcoin price in USD",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the current Bitcoin price in USD",
|
||||
"url": "https://coinmarketcap.com/currencies/bitcoin/",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"price": {
|
||||
"type": "number",
|
||||
"description": "Current Bitcoin price in USD"
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"price": 104521.37
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### List of items
|
||||
|
||||
Extract multiple items with the same structure, such as the top posts from a news site:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the top 5 posts",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"posts": {
|
||||
"type": "array",
|
||||
"description": "Top 5 posts from the front page",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Post title"
|
||||
},
|
||||
"points": {
|
||||
"type": "integer",
|
||||
"description": "Number of points"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "Link to the post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the top 5 posts",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
posts: {
|
||||
type: "array",
|
||||
description: "Top 5 posts from the front page",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "Post title",
|
||||
},
|
||||
points: {
|
||||
type: "integer",
|
||||
description: "Number of points",
|
||||
},
|
||||
url: {
|
||||
type: "string",
|
||||
description: "Link to the post",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the top 5 posts",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"posts": {
|
||||
"type": "array",
|
||||
"description": "Top 5 posts from the front page",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Post title"
|
||||
},
|
||||
"points": {
|
||||
"type": "integer",
|
||||
"description": "Number of points"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "Link to the post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"posts": [
|
||||
{
|
||||
"title": "Running Claude Code dangerously (safely)",
|
||||
"points": 342,
|
||||
"url": "https://blog.emilburzo.com/2026/01/running-claude-code-dangerously-safely/"
|
||||
},
|
||||
{
|
||||
"title": "Linux kernel framework for PCIe device emulation",
|
||||
"points": 287,
|
||||
"url": "https://github.com/cakehonolulu/pciem"
|
||||
},
|
||||
{
|
||||
"title": "I'm addicted to being useful",
|
||||
"points": 256,
|
||||
"url": "https://www.seangoedecke.com/addicted-to-being-useful/"
|
||||
},
|
||||
{
|
||||
"title": "Level S4 solar radiation event",
|
||||
"points": 198,
|
||||
"url": "https://www.swpc.noaa.gov/news/g4-severe-geomagnetic-storm"
|
||||
},
|
||||
{
|
||||
"title": "WebAssembly Text Format parser performance",
|
||||
"points": 176,
|
||||
"url": "https://blog.gplane.win/posts/improve-wat-parser-perf.html"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Arrays without limits extract everything visible on the page. Specify limits in your prompt (e.g., "top 5 posts") or the array description to control output size.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
### Nested objects
|
||||
|
||||
Extract hierarchical data, such as a product with its pricing and availability:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get product details including pricing and availability",
|
||||
url="https://www.amazon.com/dp/B0EXAMPLE",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"product": {
|
||||
"type": "object",
|
||||
"description": "Product information",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Product name"
|
||||
},
|
||||
"pricing": {
|
||||
"type": "object",
|
||||
"description": "Pricing details",
|
||||
"properties": {
|
||||
"current_price": {
|
||||
"type": "number",
|
||||
"description": "Current price in USD"
|
||||
},
|
||||
"original_price": {
|
||||
"type": "number",
|
||||
"description": "Original price before discount"
|
||||
},
|
||||
"discount_percent": {
|
||||
"type": "integer",
|
||||
"description": "Discount percentage"
|
||||
}
|
||||
}
|
||||
},
|
||||
"availability": {
|
||||
"type": "object",
|
||||
"description": "Stock information",
|
||||
"properties": {
|
||||
"in_stock": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the item is in stock"
|
||||
},
|
||||
"delivery_estimate": {
|
||||
"type": "string",
|
||||
"description": "Estimated delivery date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get product details including pricing and availability",
|
||||
url: "https://www.amazon.com/dp/B0EXAMPLE",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
product: {
|
||||
type: "object",
|
||||
description: "Product information",
|
||||
properties: {
|
||||
name: {
|
||||
type: "string",
|
||||
description: "Product name",
|
||||
},
|
||||
pricing: {
|
||||
type: "object",
|
||||
description: "Pricing details",
|
||||
properties: {
|
||||
current_price: {
|
||||
type: "number",
|
||||
description: "Current price in USD",
|
||||
},
|
||||
original_price: {
|
||||
type: "number",
|
||||
description: "Original price before discount",
|
||||
},
|
||||
discount_percent: {
|
||||
type: "integer",
|
||||
description: "Discount percentage",
|
||||
},
|
||||
},
|
||||
},
|
||||
availability: {
|
||||
type: "object",
|
||||
description: "Stock information",
|
||||
properties: {
|
||||
in_stock: {
|
||||
type: "boolean",
|
||||
description: "Whether the item is in stock",
|
||||
},
|
||||
delivery_estimate: {
|
||||
type: "string",
|
||||
description: "Estimated delivery date",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get product details including pricing and availability",
|
||||
"url": "https://www.amazon.com/dp/B0EXAMPLE",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"product": {
|
||||
"type": "object",
|
||||
"description": "Product information",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Product name"
|
||||
},
|
||||
"pricing": {
|
||||
"type": "object",
|
||||
"description": "Pricing details",
|
||||
"properties": {
|
||||
"current_price": {
|
||||
"type": "number",
|
||||
"description": "Current price in USD"
|
||||
},
|
||||
"original_price": {
|
||||
"type": "number",
|
||||
"description": "Original price before discount"
|
||||
},
|
||||
"discount_percent": {
|
||||
"type": "integer",
|
||||
"description": "Discount percentage"
|
||||
}
|
||||
}
|
||||
},
|
||||
"availability": {
|
||||
"type": "object",
|
||||
"description": "Stock information",
|
||||
"properties": {
|
||||
"in_stock": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the item is in stock"
|
||||
},
|
||||
"delivery_estimate": {
|
||||
"type": "string",
|
||||
"description": "Estimated delivery date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"product": {
|
||||
"name": "Wireless Bluetooth Headphones",
|
||||
"pricing": {
|
||||
"current_price": 79.99,
|
||||
"original_price": 129.99,
|
||||
"discount_percent": 38
|
||||
},
|
||||
"availability": {
|
||||
"in_stock": true,
|
||||
"delivery_estimate": "Tomorrow, Jan 21"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessing extracted data
|
||||
|
||||
How you access extracted data depends on which method you used.
|
||||
|
||||
### page.extract (browser automation)
|
||||
|
||||
`page.extract` returns the extracted data directly as the return value:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
data = await page.extract(
|
||||
"Get the top post",
|
||||
schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {"type": "string", "description": "Post title"},
|
||||
"points": {"type": "integer", "description": "Points"}
|
||||
}
|
||||
},
|
||||
)
|
||||
|
||||
# data is the extracted result directly
|
||||
print(f"Title: {data['title']}")
|
||||
print(f"Points: {data['points']}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const data = await page.extract({
|
||||
prompt: "Get the top post",
|
||||
schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: { type: "string", description: "Post title" },
|
||||
points: { type: "integer", description: "Points" },
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// data is the extracted result directly
|
||||
console.log(`Title: ${data.title}`);
|
||||
console.log(`Points: ${data.points}`);
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### run_task (async task)
|
||||
|
||||
The extracted data appears in the `output` field of the completed run. Poll until the task reaches a terminal state, then access the output.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the top post",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {"type": "string", "description": "Post title"},
|
||||
"points": {"type": "integer", "description": "Points"}
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
run_id = result.run_id
|
||||
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
|
||||
await asyncio.sleep(5)
|
||||
|
||||
# Access the extracted data
|
||||
print(f"Output: {run.output}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the top post",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: { type: "string", description: "Post title" },
|
||||
points: { type: "integer", description: "Points" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
const runId = result.run_id;
|
||||
|
||||
while (true) {
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
|
||||
console.log(`Output: ${JSON.stringify(run.output)}`);
|
||||
break;
|
||||
}
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 5000));
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
RUN_ID="your_run_id_here"
|
||||
|
||||
while true; do
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo "$RESPONSE" | jq -r '.status')
|
||||
|
||||
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
|
||||
echo "$RESPONSE" | jq '.output'
|
||||
break
|
||||
fi
|
||||
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
If using webhooks, the same `output` field appears in the webhook payload.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Actions Reference"
|
||||
icon="sliders"
|
||||
href="/developers/browser-automations/actions-reference"
|
||||
>
|
||||
All available page actions and agent methods
|
||||
</Card>
|
||||
<Card
|
||||
title="Build a Browser Automation"
|
||||
icon="play"
|
||||
href="/developers/browser-automations/overview"
|
||||
>
|
||||
Launch a browser, navigate pages, and extract data
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Handle Browsers
|
||||
subtitle: Launch, connect, configure, and manage browser sessions
|
||||
description: Launch cloud browsers, connect via CDP, configure proxies and timeouts, open multiple tabs, and manage browser lifecycle for Skyvern automations.
|
||||
slug: developers/browser-automations/handle-browsers
|
||||
keywords:
|
||||
- launch_cloud_browser
|
||||
- use_cloud_browser
|
||||
- connect_to_cloud_browser_session
|
||||
- connect_to_browser_over_cdp
|
||||
- launch_local_browser
|
||||
- get_working_page
|
||||
- new_page
|
||||
- close
|
||||
- proxy
|
||||
- CDP
|
||||
- session timeout
|
||||
---
|
||||
|
||||
Every browser automation starts with a browser. You launch a cloud Chromium instance, get a Playwright context, and write your automation against it. Cookies, localStorage, and auth state persist across every page you open inside that browser.
|
||||
|
||||
This page covers browser lifecycle for code-based automations using the Skyvern SDK. If you're running automations through the Cloud UI workflow editor, browser management is handled automatically. See [Browser Sessions](/cloud/browser-management/browser-sessions) for the Cloud UI equivalent.
|
||||
|
||||
---
|
||||
|
||||
## Launch a cloud browser
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `timeout` | `int` | `None` | Session timeout in minutes (5-1440). Server default: 60 minutes |
|
||||
| `proxy_location` | `ProxyLocation` | `None` | Route traffic through a geographic proxy |
|
||||
|
||||
The browser stays alive until `timeout` expires or you call `browser.close()`.
|
||||
|
||||
After a successful launch the handle exposes:
|
||||
|
||||
- `browser.browser_session_id`: the `pbs_*` session id, useful for locking tasks to this session or for logging
|
||||
- `browser.pages`: the list of open Playwright pages in this browser context
|
||||
|
||||
If `timeout < 5`, Skyvern rejects the request with `UnprocessableEntityError` (422). An invalid `proxy_location` enum is rejected the same way.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Launch with a 2-hour timeout and US residential proxy
|
||||
browser = await skyvern.launch_cloud_browser(
|
||||
timeout=120,
|
||||
proxy_location="RESIDENTIAL"
|
||||
)
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser({
|
||||
timeout: 120,
|
||||
proxyLocation: "RESIDENTIAL",
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Reuse an existing browser
|
||||
|
||||
If you have a cloud browser session already running, reuse it instead of launching a new one.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Reuse the most recent available session, or create one if none exists
|
||||
browser = await skyvern.use_cloud_browser()
|
||||
|
||||
# Connect to a specific session by ID
|
||||
browser = await skyvern.connect_to_cloud_browser_session("pbs_abc123")
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
|
||||
// Reuse the most recent available session, or create one if none exists
|
||||
const browser = await skyvern.useCloudBrowser();
|
||||
|
||||
// Connect to a specific session by ID
|
||||
const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
`use_cloud_browser` checks for an available session first. If one exists, it connects to it. If not, it creates a new one with the options you provide.
|
||||
|
||||
Passing an unknown session id to `connect_to_cloud_browser_session` raises `NotFoundError` (HTTP 404).
|
||||
|
||||
---
|
||||
|
||||
## Connect to a local browser
|
||||
|
||||
Connect to any browser running with Chrome DevTools Protocol (CDP) enabled. This works with local Chrome, Chromium, or any CDP-compatible browser.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Start Chrome with CDP enabled:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
|
||||
|
||||
# Linux
|
||||
google-chrome --remote-debugging-port=9222
|
||||
```
|
||||
|
||||
For self-hosted Skyvern deployments, you can also launch a local Chromium browser directly (Python only):
|
||||
|
||||
```python
|
||||
# Requires Skyvern.local() - not available in cloud mode
|
||||
skyvern = Skyvern.local()
|
||||
browser = await skyvern.launch_local_browser(headless=False, port=9222)
|
||||
```
|
||||
|
||||
See the [Self-Hosted Browser Configuration](/developers/self-hosted/browser) guide for headless/headful modes, display settings, and Docker setups.
|
||||
|
||||
---
|
||||
|
||||
## Working with pages
|
||||
|
||||
### Get the current page
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Returns the most recent page. If no pages are open, creates a new one. Each call returns a fresh `SkyvernBrowserPage` wrapper. Don't rely on identity (`is` / `===`) comparisons between the return value and earlier page references.
|
||||
|
||||
### Open a new tab
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
page2 = await browser.new_page()
|
||||
await page2.goto("https://example.com/other-page")
|
||||
```
|
||||
```typescript TypeScript
|
||||
const page2 = await browser.newPage();
|
||||
await page2.goto("https://example.com/other-page");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Both pages share the same browser context (cookies, auth state).
|
||||
|
||||
### Wrap an existing Playwright page (Python only)
|
||||
|
||||
```python
|
||||
skyvern_page = await browser.get_page_for(existing_playwright_page)
|
||||
```
|
||||
|
||||
Adds AI methods to a Playwright page you already have.
|
||||
|
||||
---
|
||||
|
||||
## Close the browser
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await browser.close()
|
||||
```
|
||||
```typescript TypeScript
|
||||
await browser.close();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Closes the browser and releases cloud resources. If connected to a cloud session, the session ends. Any unsaved state (cookies, localStorage) is lost unless you saved a [browser profile](/developers/optimization/browser-profiles) first.
|
||||
|
||||
---
|
||||
|
||||
## Proxy and geolocation
|
||||
|
||||
Route browser traffic through residential proxies in specific countries.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser(
|
||||
proxy_location="RESIDENTIAL"
|
||||
)
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser({
|
||||
proxyLocation: "RESIDENTIAL",
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Available locations:
|
||||
|
||||
| Value | Region |
|
||||
|-------|--------|
|
||||
| `RESIDENTIAL` | United States (default) |
|
||||
| `RESIDENTIAL_GB` | United Kingdom |
|
||||
| `RESIDENTIAL_DE` | Germany |
|
||||
| `RESIDENTIAL_ES` | Spain |
|
||||
| `RESIDENTIAL_FR` | France |
|
||||
| `RESIDENTIAL_IE` | Ireland |
|
||||
| `RESIDENTIAL_IN` | India |
|
||||
| `RESIDENTIAL_JP` | Japan |
|
||||
| `RESIDENTIAL_AU` | Australia |
|
||||
| `RESIDENTIAL_CA` | Canada |
|
||||
| `NONE` | No proxy (direct connection) |
|
||||
|
||||
For self-hosted proxy configuration, see [Proxy Setup](/developers/self-hosted/proxy).
|
||||
|
||||
---
|
||||
|
||||
## Session persistence
|
||||
|
||||
Two mechanisms for preserving browser state between automation runs:
|
||||
|
||||
**Browser Sessions** keep a browser alive between API calls. Use `create_browser_session` from the [Tasks API](/sdk-reference/tasks/run-task) to create a session, then pass its ID to multiple `run_task` calls. See [Browser Sessions](/developers/optimization/browser-sessions).
|
||||
|
||||
**Browser Profiles** save a snapshot of browser state (cookies, localStorage) that persists indefinitely. Create a profile from a completed run, then load it into future runs to skip login. See [Browser Profiles](/developers/optimization/browser-profiles).
|
||||
|
||||
---
|
||||
|
||||
## Full reference
|
||||
|
||||
- [launch_cloud_browser](/sdk-reference/browser-automation/launch-cloud-browser)
|
||||
- [use_cloud_browser](/sdk-reference/browser-automation/use-cloud-browser)
|
||||
- [connect_to_cloud_browser_session](/sdk-reference/browser-automation/connect-to-cloud-browser-session)
|
||||
- [connect_to_browser_over_cdp](/sdk-reference/browser-automation/connect-to-browser-over-cdp)
|
||||
- [launch_local_browser](/sdk-reference/browser-automation/launch-local-browser) (Python only)
|
||||
- [get_working_page](/sdk-reference/browser-automation/get-working-page)
|
||||
- [new_page](/sdk-reference/browser-automation/new-page)
|
||||
- [get_page_for](/sdk-reference/browser-automation/get-page-for) (Python only)
|
||||
- [close](/sdk-reference/browser-automation/close)
|
||||
@@ -0,0 +1,588 @@
|
||||
---
|
||||
title: Build a Browser Automation
|
||||
subtitle: Step-by-step guide to multi-step automations with code
|
||||
description: Launch a cloud browser, interact with pages using AI and Playwright, chain agent tasks, and build complete browser automations in Python or TypeScript.
|
||||
slug: developers/browser-automations/overview
|
||||
keywords:
|
||||
- launch_cloud_browser
|
||||
- get_working_page
|
||||
- page.act
|
||||
- page.extract
|
||||
- page.validate
|
||||
- page.agent.login
|
||||
- page.agent.run_task
|
||||
- selector fallback
|
||||
- login then extract
|
||||
- multi-page
|
||||
- Playwright
|
||||
---
|
||||
|
||||
Browser automations are multi-step automations written in code. You launch a cloud browser, get a Playwright page with AI methods layered on top, and write your automation in Python or TypeScript. The code lives in your repo, runs in your CI, and deploys like any other software.
|
||||
|
||||
This is the code-first path. If you prefer building automations visually with drag-and-drop blocks, see [Workflows](/cloud/building-workflows/build-a-workflow) in the Cloud UI docs.
|
||||
|
||||
<Info>
|
||||
**Workflows vs. Browser Automation:** Workflows are built and run in the Cloud UI, no code required. Browser automations are built and run in code using Page, Agent, and Browser. Both can do multi-step work across pages. Choose based on whether your team prefers a visual editor or a code editor.
|
||||
</Info>
|
||||
|
||||
This guide walks through a real example: logging into a vendor portal, extracting invoice data, and downloading a PDF. Four steps:
|
||||
|
||||
1. **Launch a browser** and get a page
|
||||
2. **Navigate and interact** with the page using AI actions, selectors, or both
|
||||
3. **Use the agent** for complex goals like login, multi-step tasks, and file downloads
|
||||
4. **Run the script** and check results
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Launch a browser and get a page
|
||||
|
||||
Every automation starts by launching a cloud browser and getting a page. The browser is a Chromium instance hosted by Skyvern. The page is a Playwright page with AI methods added on top.
|
||||
|
||||
<Info>
|
||||
Install the SDK first if you haven't:
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
pip install skyvern
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npm install @skyvern/client
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
`pip install skyvern` is enough for Skyvern Cloud and remote API usage. If you are using embedded local mode with `Skyvern.local()` or `launch_local_browser()`, install `pip install "skyvern[local]"`. For a local self-hosted server, install `pip install "skyvern[server]"`.
|
||||
|
||||
All code snippets below run inside an async function. See the [complete example](#complete-example) for the full runnable script.
|
||||
</Info>
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
skyvern = Skyvern(api_key="YOUR_API_KEY")
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The browser stays alive until you call `browser.close()` or the session times out (default: 60 minutes). All pages inside it share cookies, localStorage, and auth state.
|
||||
|
||||
For browser launch options (timeouts, proxies, connecting to local browsers), see [Managing Browsers](/developers/browser-automations/handle-browsers).
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Navigate and interact with the page
|
||||
|
||||
Once you have a page, you can interact with it using standard Playwright, AI actions, or both. For the full list of available methods and parameters, see the [Actions Reference](/developers/browser-automations/actions-reference).
|
||||
|
||||
### Navigate
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.goto("https://vendor-portal.example.com")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.goto("https://vendor-portal.example.com");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use AI actions (no selectors needed)
|
||||
|
||||
Four methods let you interact with the page using natural language. Skyvern screenshots the page and determines which elements to target.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Perform any action. Returns None.
|
||||
await page.act("Click the login button")
|
||||
|
||||
# Extract structured data. Returns dict (or list if schema root is array).
|
||||
data = await page.extract(
|
||||
"Extract all product names and prices",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"price": {"type": "number"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Check page state. Returns bool.
|
||||
is_logged_in = await page.validate("The user is logged in")
|
||||
|
||||
# Ask the AI a question. Returns {"llm_response": str}.
|
||||
result = await page.prompt("What is the total at the bottom of the table?")
|
||||
answer = result["llm_response"]
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Perform any action. Returns void.
|
||||
await page.act("Click the login button");
|
||||
|
||||
// Extract structured data. Returns object (or array if schema root is array).
|
||||
const data = await page.extract({
|
||||
prompt: "Extract all product names and prices",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
name: { type: "string" },
|
||||
price: { type: "number" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Check page state. Returns boolean.
|
||||
const isLoggedIn = await page.validate("The user is logged in");
|
||||
|
||||
// Ask the AI a question. Returns { llmResponse: string }.
|
||||
const result = await page.prompt("What is the total at the bottom of the table?");
|
||||
const answer = result.llmResponse;
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use selectors with AI fallback
|
||||
|
||||
`click`, `fill`, and `select_option` accept both a CSS selector and an AI prompt. The selector runs first. If it fails, the AI takes over.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Selector only (fast, deterministic)
|
||||
await page.click("#submit-button")
|
||||
await page.fill("#email", value="user@example.com")
|
||||
|
||||
# AI only (no selector needed, resilient to layout changes)
|
||||
await page.click(prompt="Click the 'Submit' button")
|
||||
await page.fill(prompt="Fill 'user@example.com' in the email field")
|
||||
|
||||
# Both - selector first, AI fallback (best for production)
|
||||
await page.click("#submit-button", prompt="Click the 'Submit' button")
|
||||
await page.fill("#email", value="user@example.com", prompt="Fill the email field")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Selector only (fast, deterministic)
|
||||
await page.click("#submit-button");
|
||||
await page.fill("#email", "user@example.com");
|
||||
|
||||
// AI only (no selector needed, resilient to layout changes)
|
||||
await page.click({ prompt: "Click the 'Submit' button" });
|
||||
await page.fill({ prompt: "Fill 'user@example.com' in the email field" });
|
||||
|
||||
// Both - selector first, AI fallback (best for production)
|
||||
await page.click("#submit-button", { prompt: "Click the 'Submit' button" });
|
||||
await page.fill("#email", "user@example.com", { prompt: "Fill the email field" });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Mix Playwright and AI
|
||||
|
||||
Standard Playwright methods work directly. Use selectors where you know the DOM, AI where you don't.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.goto("https://example.com/login")
|
||||
await page.fill("#username", value="demo@example.com") # Playwright - known selector
|
||||
await page.fill("#password", value="s3cur3-p4ss") # Playwright - known selector
|
||||
await page.click(prompt="Click the sign-in button") # AI - button text varies
|
||||
await page.wait_for_selector("#dashboard") # Playwright - wait for page load
|
||||
data = await page.extract("Extract the account balance") # AI - table layout varies
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.goto("https://example.com/login");
|
||||
await page.fill("#username", "demo@example.com"); // Playwright - known selector
|
||||
await page.fill("#password", "s3cur3-p4ss"); // Playwright - known selector
|
||||
await page.click({ prompt: "Click the sign-in button" }); // AI - button text varies
|
||||
await page.waitForSelector("#dashboard"); // Playwright - wait for page load
|
||||
const data = await page.extract({ prompt: "Extract the account balance" }); // AI
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Use the agent for complex goals
|
||||
|
||||
For multi-step goals ("log in with 2FA", "navigate to billing and download the invoice"), hand off to the agent. The agent runs a full AI task loop inside your page, preserving all browser state.
|
||||
|
||||
### Login with stored credentials
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.login(
|
||||
credential_type="skyvern",
|
||||
credential_id="cred_123"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The agent handles multi-page login flows, CAPTCHAs, and 2FA automatically. Four credential providers: `skyvern` (built-in vault), `bitwarden`, `onepassword`, `azure_vault`. Store credentials via the [Credentials API](/sdk-reference/credentials/create-credential).
|
||||
|
||||
### Run a multi-step task
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await page.agent.run_task(
|
||||
"Go to the billing page and extract all invoice details",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
)
|
||||
print(result.output)
|
||||
# {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await page.agent.runTask(
|
||||
"Go to the billing page and extract all invoice details",
|
||||
{
|
||||
dataExtractionSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
);
|
||||
console.log(result.output);
|
||||
// {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
After the agent finishes, you take back control. The page retains all state:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.run_task("Navigate to the settings page")
|
||||
# Agent is done - use direct page actions
|
||||
settings = await page.extract("Extract all notification preferences")
|
||||
await page.click("#save-button")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.runTask("Navigate to the settings page");
|
||||
// Agent is done - use direct page actions
|
||||
const settings = await page.extract({ prompt: "Extract all notification preferences" });
|
||||
await page.click("#save-button");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Download files
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await page.agent.download_files(
|
||||
"Download the Q4 2025 financial report",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"Downloaded: {file.url}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the Q4 2025 financial report",
|
||||
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
|
||||
);
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`Downloaded: ${file.url}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Run a workflow on the page
|
||||
|
||||
If you have built a workflow, run it on a page you already control:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
|
||||
result = await page.agent.run_workflow(
|
||||
"wpid_monthly_report",
|
||||
parameters={"month": "2025-03"}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
const result = await page.agent.runWorkflow("wpid_monthly_report", {
|
||||
parameters: { month: "2025-03" },
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**`agent.run_workflow` vs `skyvern.run_workflow`:** The top-level `run_workflow` opens its own browser. Use `agent.run_workflow` when you need to log in first or do setup before the workflow runs.
|
||||
|
||||
---
|
||||
|
||||
## Complete example
|
||||
|
||||
Putting it all together: log into a vendor portal, extract invoices, and download a statement.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
skyvern = Skyvern(api_key="YOUR_API_KEY")
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
|
||||
# Navigate
|
||||
await page.goto("https://vendor-portal.example.com")
|
||||
|
||||
# Login with stored credentials
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_abc123")
|
||||
|
||||
# Extract data using a mix of Playwright and AI
|
||||
await page.click("#billing-tab")
|
||||
invoices = await page.extract(
|
||||
"Extract all invoice numbers, dates, and amounts",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"date": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Download a file
|
||||
result = await page.agent.download_files(
|
||||
"Download the latest monthly statement",
|
||||
download_suffix=".pdf",
|
||||
)
|
||||
|
||||
# Check results
|
||||
print(f"Found {len(invoices)} invoices")
|
||||
for inv in invoices:
|
||||
print(f" {inv['invoice_number']}: {inv['amount']}")
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"Downloaded: {file.url}")
|
||||
|
||||
await browser.close()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
|
||||
// Navigate
|
||||
await page.goto("https://vendor-portal.example.com");
|
||||
|
||||
// Login with stored credentials
|
||||
await page.agent.login("skyvern", { credentialId: "cred_abc123" });
|
||||
|
||||
// Extract data using a mix of Playwright and AI
|
||||
await page.click("#billing-tab");
|
||||
const invoices = await page.extract({
|
||||
prompt: "Extract all invoice numbers, dates, and amounts",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
date: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Download a file
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the latest monthly statement",
|
||||
{ downloadSuffix: ".pdf" },
|
||||
);
|
||||
|
||||
// Check results
|
||||
console.log(`Found ${invoices.length} invoices`);
|
||||
for (const inv of invoices) {
|
||||
console.log(` ${inv.invoice_number}: ${inv.amount}`);
|
||||
}
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`Downloaded: ${file.url}`);
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Run and get results
|
||||
|
||||
Run the script:
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
python your_automation.py
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npx tsx your_automation.ts
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
You'll see the browser session URL in the console output. Open it in your browser to watch the automation run in real time.
|
||||
|
||||
### Example output
|
||||
|
||||
Here's what the Complete Example prints, grouped by the call that produced each block:
|
||||
|
||||
```text wrap
|
||||
# skyvern.launch_cloud_browser()
|
||||
[Skyvern] Launched new cloud browser session url=https://app.skyvern.com/browser-session/pbs_519895987620976102
|
||||
|
||||
# page.agent.login(...)
|
||||
[Skyvern] AI login workflow finished run_id=wr_519896041203554782 status=completed
|
||||
|
||||
# page.extract(...)
|
||||
[Skyvern] AI extract prompt=Extract all invoice numbers, dates, and amounts
|
||||
|
||||
# page.agent.download_files(...)
|
||||
[Skyvern] Starting AI file download workflow navigation_goal=Download the latest monthly statement
|
||||
[Skyvern] AI file download workflow is running, this may take a while run_id=wr_519896107880060430
|
||||
[Skyvern] AI file download workflow finished run_id=wr_519896107880060430 status=completed
|
||||
|
||||
# print(f"Found {len(invoices)} invoices") + for inv in invoices: print(...)
|
||||
Found 3 invoices
|
||||
INV-2025-042: $2,340.00
|
||||
INV-2025-043: $1,850.00
|
||||
INV-2025-044: $3,100.00
|
||||
|
||||
# for file in result.downloaded_files: print(f"Downloaded: {file.url}")
|
||||
Downloaded: https://skyvern-uploads.s3.amazonaws.com/downloads/production/o_510.../wr_519.../statement.pdf?AWS...
|
||||
```
|
||||
|
||||
The `[Skyvern] ...` lines come from the SDK's built-in logger and stream in real time as each call runs. Your own `print` output appears after the awaited call returns.
|
||||
|
||||
For the full response shape, see [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) and [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse).
|
||||
|
||||
### View results in the Cloud UI
|
||||
|
||||
Every run appears in the [Runs page](https://app.skyvern.com/runs). Click any run to see:
|
||||
- **Recording** - video of the browser session
|
||||
- **Actions** - step-by-step timeline with screenshots and AI reasoning
|
||||
- **Output** - extracted data as JSON
|
||||
- **Artifacts** - screenshots, HAR files, generated code
|
||||
|
||||
### Artifacts
|
||||
|
||||
Every run captures recordings, screenshots, AI reasoning logs, network HAR files, and downloaded files. Access them via the Cloud UI or programmatically:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
artifacts = await skyvern.get_run_artifacts(result.run_id)
|
||||
for artifact in artifacts:
|
||||
print(f"{artifact.artifact_type}: {artifact.uri}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const artifacts = await skyvern.getRunArtifacts(result.run_id);
|
||||
for (const artifact of artifacts) {
|
||||
console.log(`${artifact.artifact_type}: ${artifact.uri}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
For the full artifact type reference and debugging workflows, see [Using Artifacts](/developers/debugging/using-artifacts).
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Actions Reference"
|
||||
icon="list"
|
||||
href="/developers/browser-automations/actions-reference"
|
||||
>
|
||||
Every page action and agent method with parameters and return types
|
||||
</Card>
|
||||
<Card
|
||||
title="Managing Browsers"
|
||||
icon="browser"
|
||||
href="/developers/browser-automations/handle-browsers"
|
||||
>
|
||||
Launch options, multiple tabs, proxies, connecting to local browsers
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Store Credentials"
|
||||
icon="key"
|
||||
href="/sdk-reference/credentials/create-credential"
|
||||
>
|
||||
Set up credentials for automated login with the agent
|
||||
</Card>
|
||||
<Card
|
||||
title="SDK Reference"
|
||||
icon="code"
|
||||
href="/sdk-reference/complete-reference"
|
||||
>
|
||||
Every SDK method, parameter, and type on one page (Python + TypeScript)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="API Reference"
|
||||
icon="plug"
|
||||
href="/api-reference"
|
||||
>
|
||||
Full OpenAPI spec for every REST endpoint
|
||||
</Card>
|
||||
<Card
|
||||
title="llms.txt"
|
||||
icon="file-lines"
|
||||
href="https://skyvern.com/docs/llms.txt"
|
||||
>
|
||||
Machine-readable index of the entire documentation for AI coding agents
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: Work with Files
|
||||
subtitle: Download files from websites during browser automations
|
||||
description: Use agent.download_files to navigate websites, find download links, and retrieve files. Access downloaded files via presigned URLs.
|
||||
slug: developers/browser-automations/work-with-files
|
||||
keywords:
|
||||
- download_files
|
||||
- downloaded_files
|
||||
- presigned URL
|
||||
- PDF
|
||||
- invoice
|
||||
- download_suffix
|
||||
- download_timeout
|
||||
- FileInfo
|
||||
---
|
||||
|
||||
In a browser automation, `agent.download_files` navigates a page, finds the download link, and captures the file. Downloaded files are stored in Skyvern's cloud storage and returned as presigned URLs in the response.
|
||||
|
||||
If you're building workflows in the Cloud UI instead, use the File Download block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks).
|
||||
|
||||
---
|
||||
|
||||
## Download a file
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
|
||||
await page.goto("https://portal.example.com")
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
|
||||
|
||||
result = await page.agent.download_files(
|
||||
"Download the Q4 2025 financial report",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"File: {file.filename}")
|
||||
print(f"URL: {file.url}")
|
||||
print(f"Checksum: {file.checksum}")
|
||||
|
||||
await browser.close()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
|
||||
await page.goto("https://portal.example.com");
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the Q4 2025 financial report",
|
||||
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
|
||||
);
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`File: ${file.filename}`);
|
||||
console.log(`URL: ${file.url}`);
|
||||
console.log(`Checksum: ${file.checksum}`);
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` / `string` | Yes | Describe what to download. The agent navigates the page to find and click the download link. |
|
||||
| `url` | `str` / `string` | No | URL to navigate to before downloading. Defaults to the current page URL. |
|
||||
| `download_suffix` | `str` / `string` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). **Not a validator**; mismatched extensions don't fail the run. Omit this to get a system-generated filename like `download-<timestamp>-<random>.pdf`. |
|
||||
| `download_timeout` | `float` / `number` | No | Soft hint (seconds) for how long to wait for a download to start. Not a hard cap; the overall `timeout` below governs failure. |
|
||||
| `max_steps_per_run` | `int` / `number` | No | Cap AI steps for the download navigation. |
|
||||
| `timeout` | `float` / `number` | No | Total timeout in seconds (default: 1800). |
|
||||
|
||||
---
|
||||
|
||||
## Response
|
||||
|
||||
`agent.download_files` returns a `WorkflowRunResponse`. The downloaded files are in the `downloaded_files` field.
|
||||
|
||||
### Response fields
|
||||
|
||||
Most-used fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `run_id` | `str` | Run identifier (prefix: `wr_`) |
|
||||
| `status` | `str` | `completed`, `failed`, `terminated`, `timed_out`, or `canceled` |
|
||||
| `downloaded_files` | `list[FileInfo]` | Files captured during the run |
|
||||
| `output` | `dict \| None` | Any extracted data (may be `None` even on `completed`) |
|
||||
| `app_url` | `str` | Link to view this run in the Cloud UI |
|
||||
| `recording_url` | `str \| None` | Video recording of the download session |
|
||||
| `failure_reason` | `str \| None` | Error description if the download failed |
|
||||
| `step_count` | `int` | Number of AI steps taken |
|
||||
|
||||
See the [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) reference for the full field list.
|
||||
|
||||
### FileInfo fields
|
||||
|
||||
Each file in `downloaded_files` has:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `url` | `str` | Presigned URL to download the file. Valid for a limited time. |
|
||||
| `filename` | `str \| None` | Saved filename. Reflects `download_suffix` if you set one, otherwise system-generated. |
|
||||
| `checksum` | `str \| None` | SHA-256 checksum for integrity verification |
|
||||
| `file_size` | `int \| None` | Size of the file in bytes |
|
||||
| `modified_at` | `datetime \| None` | Last-modified timestamp if the source provides one |
|
||||
|
||||
---
|
||||
|
||||
## Where files are stored
|
||||
|
||||
Files are stored in Skyvern's managed cloud storage (S3). You access them through the presigned URLs returned in `downloaded_files`. Files are not saved to your local machine automatically.
|
||||
|
||||
To save a file locally:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import requests
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
response = requests.get(file.url)
|
||||
with open(file.filename or "download.pdf", "wb") as f:
|
||||
f.write(response.content)
|
||||
print(f"Saved {file.filename}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import fs from "fs";
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
const response = await fetch(file.url);
|
||||
const buffer = await response.arrayBuffer();
|
||||
fs.writeFileSync(file.filename ?? "download.pdf", Buffer.from(buffer));
|
||||
console.log(`Saved ${file.filename}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Set `download_suffix`** to get a predictable filename (e.g., `"invoice-q4"` → `invoice-q4.pdf`). Without it, files are saved with a system-generated name like `download-<timestamp>-<random>.pdf`. It does **not** validate or filter by extension.
|
||||
|
||||
**Raise the overall `timeout`** for large files. `download_timeout` is a soft hint; `timeout` is what actually fails the run.
|
||||
|
||||
**Verify with checksums.** The `checksum` field contains a SHA-256 hash. Compare it against expected values to verify file integrity.
|
||||
|
||||
**Login first.** Most download portals require authentication. Call `agent.login` before `agent.download_files` - the agent reuses the authenticated session.
|
||||
|
||||
---
|
||||
|
||||
## File operations in workflows
|
||||
|
||||
If you build workflows in the Cloud UI, file operations use dedicated blocks instead of `agent.download_files`:
|
||||
|
||||
| Block | Purpose |
|
||||
|-------|---------|
|
||||
| **File Download** | Download files during workflow execution |
|
||||
| **File Parser** | Parse PDFs, CSVs, and Excel files |
|
||||
| **Download to S3** | Save files from URLs to Skyvern's S3 |
|
||||
| **Upload to S3** | Upload workflow files to S3 |
|
||||
| **File Upload** | Upload to your own S3 or Azure Blob Storage |
|
||||
|
||||
Files downloaded during a workflow accumulate in a temporary directory and can be passed between blocks using workflow parameters. See [Workflow Blocks Reference](/cloud/building-workflows/configure-blocks) for block configuration details.
|
||||
|
||||
---
|
||||
|
||||
## Full reference
|
||||
|
||||
- [agent.download_files](/sdk-reference/browser-automation/agent-download-files) - SDK reference with all parameter options
|
||||
- [Using Artifacts](/developers/debugging/using-artifacts) - access recordings, screenshots, and downloaded files from any run
|
||||
@@ -0,0 +1,515 @@
|
||||
---
|
||||
title: Handle 2FA
|
||||
subtitle: Configure two-factor authentication for automated logins
|
||||
description: Configure two-factor authentication for Skyvern automations using TOTP secrets, pushed verification codes, pull-based endpoints, or magic links. Supports Bitwarden TOTP integration.
|
||||
slug: developers/credentials/handle-2fa
|
||||
keywords:
|
||||
- TOTP
|
||||
- 2FA
|
||||
- totp_identifier
|
||||
- totp_url
|
||||
- authenticator
|
||||
- email code
|
||||
- SMS code
|
||||
- magic link
|
||||
- send_totp_code
|
||||
- verification
|
||||
---
|
||||
|
||||
Many websites require two-factor authentication (2FA) during login. Skyvern supports multiple 2FA methods to handle these flows automatically.
|
||||
|
||||
---
|
||||
|
||||
## Choose your method
|
||||
|
||||
Select the method that matches how you receive verification codes:
|
||||
|
||||
| Scenario | Recommended Method |
|
||||
|----------|-------------------|
|
||||
| You have the TOTP secret key | [Store TOTP secret](#method-1-store-totp-secret): Skyvern generates codes |
|
||||
| Codes sent to email/SMS you can forward | [Push codes to Skyvern](#method-2-push-codes-to-skyvern) |
|
||||
| Codes sent to a system you control | [Skyvern pulls from your endpoint](#method-3-skyvern-pulls-from-your-endpoint) |
|
||||
| Passwordless/magic link auth | [Magic links](#method-4-magic-links) |
|
||||
| Using Bitwarden with TOTP | [Password manager integration](#password-manager-totp) |
|
||||
|
||||
---
|
||||
|
||||
## Method 1: Store TOTP secret
|
||||
|
||||
**Best for:** Sites where you have access to the TOTP secret (the setup QR code or manual key).
|
||||
|
||||
When you enable 2FA on a website, you're typically shown a QR code or a secret key. Store this secret with your credential, and Skyvern generates valid codes automatically.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
credential = await client.create_credential(
|
||||
name="Acme Portal Login",
|
||||
credential_type="password",
|
||||
credential={
|
||||
"username": "user@example.com",
|
||||
"password": "secure_password",
|
||||
"totp": "JBSWY3DPEHPK3PXP", # Base32 secret from QR code
|
||||
"totp_type": "authenticator",
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { SkyvernClient } from "@skyvern/client";
|
||||
|
||||
const client = new SkyvernClient({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
const credential = await client.createCredential({
|
||||
name: "Acme Portal Login",
|
||||
credential_type: "password",
|
||||
credential: {
|
||||
username: "user@example.com",
|
||||
password: "secure_password",
|
||||
totp: "JBSWY3DPEHPK3PXP",
|
||||
totp_type: "authenticator",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Acme Portal Login",
|
||||
"credential_type": "password",
|
||||
"credential": {
|
||||
"username": "user@example.com",
|
||||
"password": "secure_password",
|
||||
"totp": "JBSWY3DPEHPK3PXP",
|
||||
"totp_type": "authenticator"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### TOTP types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `authenticator` | Standard TOTP codes (Google Authenticator, Authy, etc.) |
|
||||
| `email` | Codes sent via email that you'll push to Skyvern |
|
||||
| `text` | Codes sent via SMS that you'll push to Skyvern |
|
||||
|
||||
<Tip>
|
||||
Skyvern generates TOTP codes using standard 30-second windows. If the current code has less than 20 seconds remaining, Skyvern automatically uses the next code to ensure successful entry.
|
||||
</Tip>
|
||||
|
||||
### Finding your TOTP secret
|
||||
|
||||
Most sites show the secret when you set up 2FA:
|
||||
|
||||
1. Go to your account's security settings
|
||||
2. Click "Set up authenticator app"
|
||||
3. Look for "Can't scan the QR code?" or "Manual entry"
|
||||
4. Copy the secret key (usually Base32 format like `JBSWY3DPEHPK3PXP`)
|
||||
|
||||
<Note>
|
||||
If you've already set up 2FA and don't have the secret, you may need to disable and re-enable 2FA to see the secret again. Contact [support@skyvern.com](mailto:support@skyvern.com) for help.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Method 2: Push codes to Skyvern
|
||||
|
||||
**Best for:** Codes sent to email or SMS that you can programmatically forward.
|
||||
|
||||
When your automation encounters a 2FA prompt, Skyvern polls for codes that you push via API. Your email or SMS forwarding system sends codes to Skyvern as they arrive.
|
||||
|
||||
### Step 1: Set up code forwarding
|
||||
|
||||
Configure your email or SMS to forward verification codes to Skyvern. Common approaches:
|
||||
|
||||
- **Email:** Gmail filter + Zapier webhook
|
||||
- **SMS:** Twilio webhook to your server
|
||||
- **Email:** AWS SES + Lambda function
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="How to set up Email Forwarding with Zapier?">
|
||||
|
||||
This setup requires a Zapier Pro plan account.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Zapier Zap">
|
||||
{/* TODO: Replace with actual video */}
|
||||
<Frame>
|
||||
<video
|
||||
autoPlay
|
||||
muted
|
||||
loop
|
||||
playsInline
|
||||
className="rounded-xl"
|
||||
src="/images/zapier-forwarding-setup.mp4"
|
||||
></video>
|
||||
</Frame>
|
||||
|
||||
1. Go to [zapier.com](https://zapier.com/app/home) and create a new Zap
|
||||
2. In the newly created Zap draft, click the "Trigger" button
|
||||
3. Click **Email by Zapier**
|
||||
4. In the Email "Setup", pick **New Inbound Email** in the Trigger event selection. Click **Continue**
|
||||
5. In Email "Configure", create an email address which will be used to forward emails for TOTP codes. Click **Continue**
|
||||
6. Click the "Action" button and add **Webhooks by Zapier**
|
||||
7. In the Setup, choose **POST** under the Action event selection. Click **Continue**
|
||||
8. In the "Configure", set up these fields to make a POST request to Skyvern's TOTP API:
|
||||
- **URL:** `https://api.skyvern.com/v1/credentials/totp`
|
||||
- **Payload Type:** `json`
|
||||
- **Data:**
|
||||
- `totp_identifier`: choose **Raw To Email** after clicking the "+" sign
|
||||
- `content`: choose **Body Plain** after clicking the "+" sign
|
||||
- `source`: `email`
|
||||
- **Headers:**
|
||||
- `x-api-key`: your Skyvern API key
|
||||
9. Click **Continue**
|
||||
</Step>
|
||||
<Step title="Add forwarding email and create a filter in Gmail">
|
||||
Go to Gmail Settings → Forwarding and POP/IMAP → click **Add a forwarding address** → enter the Zapier email address you created. Complete any verification steps.
|
||||
|
||||
Then go to **Filters and Blocked Addresses**. Click **Create a new filter** and set up a filtering rule for your TOTP (2FA/MFA) emails. Click **Create filter**, check **Forward it to**, pick the Zapier email address, and update the filter.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/totp/create_email_forwarding.png" alt="Gmail forwarding filter" width="400"/>
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Test it end to end">
|
||||
Forward any previous TOTP email to the Zapier email address you created.
|
||||
|
||||
In Zapier, under the "Test" of the Webhooks action, send a request to test it out. If successful, you should see a "A request was sent to Webhooks by Zapier" message.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="How to set up SMS Forwarding with Twilio?">
|
||||
|
||||
Use a virtual phone number service like [Twilio](https://www.twilio.com/en-us/docs/usage/tutorials/how-to-use-your-free-trial-account) or [Plivo](https://www.plivo.com/) to receive SMS codes and forward them to Skyvern.
|
||||
|
||||
<Steps>
|
||||
<Step title="Set up a Twilio phone number">
|
||||
Create a Twilio account and provision a phone number. This number will receive the SMS verification codes.
|
||||
</Step>
|
||||
<Step title="Create a Twilio Function to forward codes">
|
||||
In your Twilio console, create a new Function that forwards incoming SMS to Skyvern's TOTP API:
|
||||
|
||||
```javascript
|
||||
// Twilio Function
|
||||
exports.handler = async function(context, event, callback) {
|
||||
const axios = require('axios');
|
||||
|
||||
await axios.post('https://api.skyvern.com/v1/credentials/totp', {
|
||||
totp_identifier: event.To, // Your Twilio phone number
|
||||
content: event.Body,
|
||||
source: 'phone'
|
||||
}, {
|
||||
headers: {
|
||||
'x-api-key': context.SKYVERN_API_KEY,
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
|
||||
return callback(null, new Twilio.Response());
|
||||
};
|
||||
```
|
||||
|
||||
Add your `SKYVERN_API_KEY` as an environment variable in the Twilio Function configuration.
|
||||
</Step>
|
||||
<Step title="Configure the webhook">
|
||||
In your Twilio phone number settings, set the **A Message Comes In** webhook to point to your Twilio Function URL.
|
||||
</Step>
|
||||
<Step title="Test it">
|
||||
Send a test SMS to your Twilio number and verify the code appears in Skyvern:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_TWILIO_NUMBER" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Step 2: Start the run with a TOTP identifier
|
||||
|
||||
When running your login, include a `totp_identifier` that matches what you'll use when pushing codes:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.login(
|
||||
credential_type="skyvern",
|
||||
url="https://portal.example.com/login",
|
||||
credential_id="cred_xyz789",
|
||||
totp_identifier="user@example.com", # Must match when pushing code
|
||||
)
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"credential_type": "skyvern",
|
||||
"url": "https://portal.example.com/login",
|
||||
"credential_id": "cred_xyz789",
|
||||
"totp_identifier": "user@example.com"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Step 3: Push the code when received
|
||||
|
||||
When the verification code arrives, push it to Skyvern:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await client.send_totp_code(
|
||||
totp_identifier="user@example.com",
|
||||
content="Your verification code is 123456", # Full email/SMS body
|
||||
source="email",
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await client.sendTotpCode({
|
||||
totp_identifier: "user@example.com",
|
||||
content: "Your verification code is 123456",
|
||||
source: "email",
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"totp_identifier": "user@example.com",
|
||||
"content": "Your verification code is 123456",
|
||||
"source": "email"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
If `content` is longer than 10 characters, Skyvern's AI extracts the verification code automatically. You can send the full email or SMS body without parsing it yourself.
|
||||
</Note>
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Method 3: Skyvern pulls from your endpoint
|
||||
|
||||
**Best for:** Environments where you control the system receiving 2FA codes and can expose them via an HTTP endpoint.
|
||||
|
||||
Instead of pushing codes to Skyvern, you implement an endpoint that Skyvern polls until a code is available.
|
||||
|
||||
### Step 1: Implement the endpoint
|
||||
|
||||
Your endpoint must accept POST requests and return the verification code:
|
||||
|
||||
**Request from Skyvern:**
|
||||
```http
|
||||
POST https://your-server.com/totp-webhook
|
||||
x-skyvern-signature: <hmac-sha256-signature>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task_id": "tsk_123456"
|
||||
}
|
||||
```
|
||||
|
||||
**Expected response:**
|
||||
```json
|
||||
{
|
||||
"verification_code": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Verify request signatures
|
||||
|
||||
Skyvern signs all requests using HMAC-SHA256 with your API key. Verify the signature to ensure requests are authentic:
|
||||
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
def verify_skyvern_request(request, api_key: str) -> bool:
|
||||
signature = request.headers.get("x-skyvern-signature")
|
||||
payload = request.body # bytes
|
||||
|
||||
expected = hmac.new(
|
||||
api_key.encode("utf-8"),
|
||||
msg=payload,
|
||||
digestmod=hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
return hmac.compare_digest(signature, expected)
|
||||
```
|
||||
|
||||
### Step 3: Configure the login
|
||||
|
||||
Pass `totp_url` when running your login:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.login(
|
||||
credential_type="skyvern",
|
||||
url="https://portal.example.com/login",
|
||||
credential_id="cred_xyz789",
|
||||
totp_url="https://your-server.com/totp-webhook",
|
||||
)
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"credential_type": "skyvern",
|
||||
"url": "https://portal.example.com/login",
|
||||
"credential_id": "cred_xyz789",
|
||||
"totp_url": "https://your-server.com/totp-webhook"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Skyvern polls your endpoint every 10 seconds until a code is returned or the timeout is reached.
|
||||
|
||||
---
|
||||
|
||||
## Method 4: Magic links
|
||||
|
||||
**Best for:** Passwordless authentication systems that send one-time login links.
|
||||
|
||||
When a site uses magic links instead of passwords, push the link to Skyvern:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await client.send_totp_code(
|
||||
totp_identifier="user@example.com",
|
||||
content="https://portal.example.com/login?token=abc123xyz",
|
||||
source="email",
|
||||
)
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"totp_identifier": "user@example.com",
|
||||
"content": "https://portal.example.com/login?token=abc123xyz",
|
||||
"source": "email"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
Skyvern automatically detects URLs and classifies them as magic links. The automation will navigate to the link to complete authentication.
|
||||
</Note>
|
||||
|
||||
For magic link flows, structure your workflow in two parts:
|
||||
|
||||
1. **Trigger the magic link**: Navigate to login and enter email
|
||||
2. **Complete login**: Use the magic link as the starting URL for the next step
|
||||
|
||||
---
|
||||
|
||||
## Password manager TOTP
|
||||
|
||||
If you store TOTP secrets in Bitwarden or 1Password, Skyvern can retrieve both the password and TOTP code in a single request.
|
||||
|
||||
### Bitwarden
|
||||
|
||||
Store your TOTP secret in Bitwarden's authenticator field:
|
||||
|
||||
1. Open the vault item in Bitwarden
|
||||
2. Click "Authenticator Key (TOTP)"
|
||||
3. Enter your TOTP secret or scan the QR code
|
||||
4. Skyvern retrieves both password and TOTP when using this credential
|
||||
|
||||
**Supported TOTP formats:**
|
||||
- Raw secret: `JBSWY3DPEHPK3PXP`
|
||||
- otpauth URI: `otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example`
|
||||
|
||||
### 1Password
|
||||
|
||||
Store TOTP in 1Password's one-time password field:
|
||||
|
||||
1. Edit the login item in 1Password
|
||||
2. Add a "One-Time Password" field
|
||||
3. Enter the TOTP secret or scan the QR code
|
||||
4. Reference the item in your Skyvern workflow
|
||||
|
||||
---
|
||||
|
||||
## Multi-field TOTP entry
|
||||
|
||||
Some sites split TOTP codes across multiple input fields (one digit per box). Skyvern handles this automatically:
|
||||
|
||||
1. Detects multi-field TOTP layouts
|
||||
2. Enters the same code across all fields
|
||||
3. Caches the code to prevent requesting a new one mid-entry
|
||||
|
||||
<Note>
|
||||
No special configuration needed. Skyvern's AI recognizes multi-field TOTP inputs and handles them correctly.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Timeouts and polling
|
||||
|
||||
Skyvern waits for 2FA codes based on configurable timeouts:
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| Polling interval | 10 seconds | How often Skyvern checks for new codes |
|
||||
| Polling timeout | 15 minutes | Maximum wait time before failing |
|
||||
|
||||
If you're pushing codes, ensure your forwarding pipeline delivers codes within the timeout window.
|
||||
|
||||
---
|
||||
|
||||
## List recent codes
|
||||
|
||||
Debug your 2FA integration by listing recent codes received:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com&limit=10" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
**Query parameters:**
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `totp_identifier` | Filter by identifier (email, phone, etc.) |
|
||||
| `workflow_run_id` | Filter by specific workflow run |
|
||||
| `otp_type` | Filter by type: `totp` or `magic_link` |
|
||||
| `limit` | Number of records (default 50, max 200) |
|
||||
|
||||
<Note>
|
||||
Skyvern only returns codes from the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`).
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
|
||||
Set up your credential vault integration
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
|
||||
Debug 2FA and login failures
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,495 @@
|
||||
---
|
||||
title: Store Credentials
|
||||
subtitle: Securely manage login credentials, credit cards, and API secrets
|
||||
description: Create, manage, and delete credentials using Skyvern's credential API. Store passwords, credit cards, and API secrets in Bitwarden, 1Password, Azure Key Vault, or a custom vault.
|
||||
slug: developers/credentials/store-credentials
|
||||
keywords:
|
||||
- create_credential
|
||||
- get_credentials
|
||||
- delete_credential
|
||||
- password
|
||||
- credit card
|
||||
- secret
|
||||
- Bitwarden
|
||||
- 1Password
|
||||
- Azure Key Vault
|
||||
- custom vault
|
||||
---
|
||||
|
||||
Skyvern provides a credential management layer that gives you a unified API to create, use, and delete credentials. Your actual secrets are never stored in Skyvern. They live in your external vault (Bitwarden by default, or 1Password, Azure Key Vault, or your own service).
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
When you create a credential via Skyvern's API, two things happen:
|
||||
|
||||
**Skyvern stores metadata** for easy lookup: credential names, IDs like `cred_xyz789`, usernames, and non-sensitive identifiers (like the last 4 digits of a card). This lets you list and manage credentials without exposing secrets.
|
||||
|
||||
**Your vault stores the secrets**: passwords, TOTP keys, full card numbers, and API tokens. Skyvern only retrieves these at runtime when needed, then discards them immediately after use.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Your Infrastructure
|
||||
Vault[(Your Vault<br/>Bitwarden, 1Password, Azure, etc.)]
|
||||
end
|
||||
|
||||
subgraph Skyvern
|
||||
Fetch[Fetch at runtime]
|
||||
Fill[Fill forms]
|
||||
end
|
||||
|
||||
subgraph Outputs
|
||||
Browser[Browser]
|
||||
Logs[Logs & LLM]
|
||||
end
|
||||
|
||||
Vault -->|secrets| Fetch
|
||||
Fetch -->|real values| Fill
|
||||
Fill -->|real values| Browser
|
||||
Fetch -.->|"placeholders<br/>(BW_PASSWORD)"| Logs
|
||||
```
|
||||
|
||||
This gives you:
|
||||
|
||||
- **Friendly IDs**: Reference credentials by `cred_xyz789` instead of vault-specific item IDs
|
||||
- **Vault abstraction**: Switch between Bitwarden, Azure, or custom vaults without changing your code
|
||||
- **Security by design**: Secrets never appear in logs, API responses, or LLM prompts
|
||||
|
||||
---
|
||||
|
||||
## Credential types
|
||||
|
||||
Skyvern supports three credential types, each designed for specific use cases.
|
||||
|
||||
### Password credentials
|
||||
|
||||
Store usernames, passwords, and optional TOTP secrets for website logins.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
credential = await client.create_credential(
|
||||
name="Acme Portal Login",
|
||||
credential_type="password",
|
||||
credential={
|
||||
"username": "user@example.com",
|
||||
"password": "secure_password_here",
|
||||
},
|
||||
)
|
||||
|
||||
print(f"Credential ID: {credential.credential_id}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { SkyvernClient } from "@skyvern/client";
|
||||
|
||||
const client = new SkyvernClient({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
const credential = await client.createCredential({
|
||||
name: "Acme Portal Login",
|
||||
credential_type: "password",
|
||||
credential: {
|
||||
username: "user@example.com",
|
||||
password: "secure_password_here",
|
||||
},
|
||||
});
|
||||
|
||||
console.log(`Credential ID: ${credential.credential_id}`);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Acme Portal Login",
|
||||
"credential_type": "password",
|
||||
"credential": {
|
||||
"username": "user@example.com",
|
||||
"password": "secure_password_here"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Credit card credentials
|
||||
|
||||
Store payment information for checkout automations. Skyvern only stores the last 4 digits in metadata for identification.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
credential = await client.create_credential(
|
||||
name="Corporate Card",
|
||||
credential_type="credit_card",
|
||||
credential={
|
||||
"card_number": "4242424242424242",
|
||||
"card_cvv": "123",
|
||||
"card_exp_month": "12",
|
||||
"card_exp_year": "2028",
|
||||
"card_brand": "visa",
|
||||
"card_holder_name": "John Smith",
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const credential = await client.createCredential({
|
||||
name: "Corporate Card",
|
||||
credential_type: "credit_card",
|
||||
credential: {
|
||||
card_number: "4242424242424242",
|
||||
card_cvv: "123",
|
||||
card_exp_month: "12",
|
||||
card_exp_year: "2028",
|
||||
card_brand: "visa",
|
||||
card_holder_name: "John Smith",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Corporate Card",
|
||||
"credential_type": "credit_card",
|
||||
"credential": {
|
||||
"card_number": "4242424242424242",
|
||||
"card_cvv": "123",
|
||||
"card_exp_month": "12",
|
||||
"card_exp_year": "2028",
|
||||
"card_brand": "visa",
|
||||
"card_holder_name": "John Smith"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Supported card brands:** `visa`, `mastercard`, `amex`, `discover`
|
||||
|
||||
### Secret credentials
|
||||
|
||||
Store API keys, tokens, or other sensitive strings for use in HTTP Request blocks or custom integrations.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
credential = await client.create_credential(
|
||||
name="API Key",
|
||||
credential_type="secret",
|
||||
credential={
|
||||
"secret_value": "sk-abc123xyz",
|
||||
"secret_label": "Production API Key", # optional
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const credential = await client.createCredential({
|
||||
name: "API Key",
|
||||
credential_type: "secret",
|
||||
credential: {
|
||||
secret_value: "sk-abc123xyz",
|
||||
secret_label: "Production API Key",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "API Key",
|
||||
"credential_type": "secret",
|
||||
"credential": {
|
||||
"secret_value": "sk-abc123xyz",
|
||||
"secret_label": "Production API Key"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Vault integrations
|
||||
|
||||
Skyvern integrates with external password managers so credentials never leave your infrastructure.
|
||||
|
||||
### Bitwarden
|
||||
|
||||
Connect Skyvern to your Bitwarden organization to use existing vault items.
|
||||
|
||||
**Cloud setup:**
|
||||
|
||||
1. Create a Bitwarden organization at [bitwarden.com](https://bitwarden.com)
|
||||
2. Create a collection to share with Skyvern
|
||||
3. Contact [support@skyvern.com](mailto:support@skyvern.com) to complete the integration
|
||||
4. Get your collection ID from the Bitwarden URL
|
||||
5. Reference credentials by collection ID in your workflows
|
||||
|
||||
**Self-hosted setup:**
|
||||
|
||||
For self-hosted Bitwarden or Vaultwarden, configure these environment variables:
|
||||
|
||||
```bash
|
||||
SKYVERN_AUTH_BITWARDEN_ORGANIZATION_ID=your-org-id
|
||||
SKYVERN_AUTH_BITWARDEN_MASTER_PASSWORD=your-master-password
|
||||
SKYVERN_AUTH_BITWARDEN_CLIENT_ID=user.your-client-id
|
||||
SKYVERN_AUTH_BITWARDEN_CLIENT_SECRET=your-client-secret
|
||||
BW_HOST=https://your-bitwarden-server.com
|
||||
```
|
||||
|
||||
### 1Password
|
||||
|
||||
Connect via service account tokens for secure credential access.
|
||||
|
||||
1. Create a 1Password service account with access to your vault
|
||||
2. Store the service account token in Skyvern:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/onepassword/create" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"token": "your-1password-service-account-token"
|
||||
}'
|
||||
```
|
||||
|
||||
3. Reference vault items by ID in your workflows
|
||||
|
||||
### Azure Key Vault
|
||||
|
||||
Store credentials in Azure Key Vault for enterprise environments.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/azure_credential/create" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"credential": {
|
||||
"client_id": "your-azure-client-id",
|
||||
"client_secret": "your-azure-client-secret",
|
||||
"tenant_id": "your-azure-tenant-id"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Custom HTTP vault
|
||||
|
||||
Integrate your own credential service via HTTP API. Your service must implement these endpoints:
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `{base_url}` | POST | Create credential, return `{"id": "..."}` |
|
||||
| `{base_url}/{id}` | GET | Return credential data |
|
||||
| `{base_url}/{id}` | DELETE | Delete credential |
|
||||
|
||||
Configure via environment variables:
|
||||
|
||||
```bash
|
||||
CREDENTIAL_VAULT_TYPE=custom
|
||||
CUSTOM_CREDENTIAL_API_BASE_URL=https://credentials.company.com/api/v1/credentials
|
||||
CUSTOM_CREDENTIAL_API_TOKEN=your_api_token
|
||||
```
|
||||
|
||||
Or via API for per-organization configuration:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/custom_credential/create" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"config": {
|
||||
"api_base_url": "https://credentials.company.com/api/v1/credentials",
|
||||
"api_token": "your_api_token"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using credentials in workflows
|
||||
|
||||
Workflows are the recommended way to use credentials. Add a credential parameter to your workflow, then reference it in login blocks.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Run a workflow with credential parameter
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wpid_abc123",
|
||||
parameters={
|
||||
"login_credential": "cred_xyz789", # Your credential ID
|
||||
"target_url": "https://portal.example.com",
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: "wpid_abc123",
|
||||
parameters: {
|
||||
login_credential: "cred_xyz789",
|
||||
target_url: "https://portal.example.com",
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"workflow_id": "wpid_abc123",
|
||||
"parameters": {
|
||||
"login_credential": "cred_xyz789",
|
||||
"target_url": "https://portal.example.com"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
You can also manage credentials directly from the Skyvern UI. See the [Managing Credentials](/cloud/managing-credentials/overview) guide for details.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Using credentials with login
|
||||
|
||||
For direct login automations, use the dedicated `login` method which handles credential retrieval and authentication:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.login(
|
||||
credential_type="skyvern",
|
||||
url="https://portal.example.com/login",
|
||||
credential_id="cred_xyz789",
|
||||
prompt="Navigate to the dashboard after logging in",
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.login({
|
||||
credential_type: "skyvern",
|
||||
url: "https://portal.example.com/login",
|
||||
credential_id: "cred_xyz789",
|
||||
prompt: "Navigate to the dashboard after logging in",
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"credential_type": "skyvern",
|
||||
"url": "https://portal.example.com/login",
|
||||
"credential_id": "cred_xyz789",
|
||||
"prompt": "Navigate to the dashboard after logging in"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Credential types for login:**
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `skyvern` | Use credentials created via Skyvern's API (stored in your configured vault) |
|
||||
| `bitwarden` | Directly reference Bitwarden vault items by collection/item ID |
|
||||
| `1password` | Directly reference 1Password vault items by vault/item ID |
|
||||
| `azure_vault` | Directly reference Azure Key Vault secrets by name |
|
||||
|
||||
---
|
||||
|
||||
## Managing credentials
|
||||
|
||||
### List credentials
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
credentials = await client.get_credentials()
|
||||
|
||||
for cred in credentials:
|
||||
print(f"{cred.name}: {cred.credential_id}")
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Get credential metadata
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
credential = await client.get_credential("cred_xyz789")
|
||||
print(f"Name: {credential.name}")
|
||||
print(f"Type: {credential.credential_type}")
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
The GET endpoint returns metadata only, never the actual credential values. This is by design for security.
|
||||
</Note>
|
||||
|
||||
### Delete a credential
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await client.delete_credential("cred_xyz789")
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/cred_xyz789/delete" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Warning>
|
||||
Credential deletion is permanent. Workflows using the deleted credential will fail on their next run.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Security architecture
|
||||
|
||||
Skyvern's credential handling is designed with security at every layer:
|
||||
|
||||
1. **Vault fetch**: Credentials are retrieved from your external vault only when needed
|
||||
2. **Memory only**: Values exist in Skyvern's memory briefly during execution
|
||||
3. **Placeholder tokens**: When sending data to LLMs, real values are replaced with tokens like `BW_PASSWORD`
|
||||
4. **No persistence**: Real values are never written to databases, logs, or API responses
|
||||
5. **LLM isolation**: Credentials are never sent to language models. The LLM sees only placeholder tokens
|
||||
|
||||
<Note>
|
||||
When you view a run's artifacts or recordings, you'll see placeholder values like `BW_PASSWORD`, `BW_USERNAME`, or `BW_TOTP` instead of actual credentials.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
|
||||
Set up two-factor authentication for your automations
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
|
||||
Debug common login failures
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,349 @@
|
||||
---
|
||||
title: Troubleshooting Login Failures
|
||||
subtitle: Debug common authentication issues in your automations
|
||||
description: Debug common login failures in Skyvern automations including credential errors, expired 2FA codes, CAPTCHA blocks, SSO redirects, and multi-step login flows. Includes a step-by-step debugging checklist.
|
||||
slug: developers/credentials/troubleshooting-login
|
||||
keywords:
|
||||
- login failure
|
||||
- debug
|
||||
- expired code
|
||||
- CAPTCHA block
|
||||
- SSO redirect
|
||||
- multi-step login
|
||||
- session timeout
|
||||
- checklist
|
||||
- recording
|
||||
- screenshot
|
||||
---
|
||||
|
||||
Login failures are the most common issue in web automation. This guide covers the most frequent problems and how to resolve them.
|
||||
|
||||
---
|
||||
|
||||
## Common failure patterns
|
||||
|
||||
### Credentials not entered
|
||||
|
||||
**Symptoms:** Task completes but login never happened. The final screenshot shows the login page.
|
||||
|
||||
**Causes:**
|
||||
- Credential parameter not linked to workflow
|
||||
- Wrong `credential_id` referenced
|
||||
- Vault connection failed
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify the credential exists:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
2. Check workflow parameter configuration to ensure the credential parameter is linked to a Login block
|
||||
|
||||
3. For vault integrations (Bitwarden, 1Password), verify connectivity:
|
||||
- Check vault credentials are valid
|
||||
- Ensure collection/vault IDs are correct
|
||||
- Test vault access independently
|
||||
|
||||
---
|
||||
|
||||
### Wrong credentials entered
|
||||
|
||||
**Symptoms:** Site shows "Invalid username or password" error.
|
||||
|
||||
**Causes:**
|
||||
- Credentials stored incorrectly in your vault
|
||||
- Site expects different format (email vs username)
|
||||
- Password contains special characters causing issues
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify credentials work manually**: Log in to the site yourself with the same credentials
|
||||
|
||||
2. **Check username format**: Some sites require email, others want a username:
|
||||
```
|
||||
❌ john.smith
|
||||
✓ john.smith@company.com
|
||||
```
|
||||
|
||||
3. **Test credential retrieval**: Create a simple test task to verify Skyvern can access the credential
|
||||
|
||||
4. **Check for copy/paste errors**: Re-enter credentials in your vault, avoiding trailing spaces
|
||||
|
||||
---
|
||||
|
||||
### 2FA code expired
|
||||
|
||||
**Symptoms:** "Invalid code" or "Code expired" error after entering TOTP.
|
||||
|
||||
**Causes:**
|
||||
- Clock drift between Skyvern and your authenticator
|
||||
- Code fetched too early in the 30-second window
|
||||
- Multi-field entry took too long
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Skyvern handles timing automatically**: If a TOTP code has less than 20 seconds remaining, Skyvern uses the next code
|
||||
|
||||
2. **For pushed codes**: Ensure your forwarding pipeline sends codes promptly. Delays over 30 seconds cause expiration.
|
||||
|
||||
3. **Check system clocks**: If self-hosting, ensure your server time is synchronized (NTP)
|
||||
|
||||
4. **Retry the run**: Intermittent timing issues often resolve on retry
|
||||
|
||||
---
|
||||
|
||||
### 2FA code never received
|
||||
|
||||
**Symptoms:** Task times out waiting for verification code.
|
||||
|
||||
**Causes:**
|
||||
- Push endpoint not forwarding codes
|
||||
- `totp_url` returning errors
|
||||
- `totp_identifier` mismatch between run and push
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify your push endpoint**: Check that it's receiving and forwarding codes:
|
||||
|
||||
```bash
|
||||
# Test your Zapier/webhook endpoint manually
|
||||
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"totp_identifier": "user@example.com",
|
||||
"content": "Your code is 123456",
|
||||
"source": "email"
|
||||
}'
|
||||
```
|
||||
|
||||
2. **Check `totp_identifier` matches**: The identifier in your login must exactly match what you push:
|
||||
|
||||
```python
|
||||
# These must match exactly
|
||||
result = await client.login(
|
||||
credential_type="skyvern",
|
||||
credential_id="cred_xyz789",
|
||||
totp_identifier="user@example.com", # ← This
|
||||
...
|
||||
)
|
||||
|
||||
await client.send_totp_code(
|
||||
totp_identifier="user@example.com", # ← Must match this
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
3. **List recent codes** to verify they're being received:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
4. **For pull-based 2FA**: Check your endpoint returns the correct format:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "tsk_123456",
|
||||
"verification_code": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Site-specific issues
|
||||
|
||||
### CAPTCHA blocking login
|
||||
|
||||
**Symptoms:** Login page shows CAPTCHA challenge that blocks automation.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use residential proxies**: Many CAPTCHAs trigger on datacenter IPs:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
url="https://portal.example.com/login",
|
||||
prompt="Log in to the portal",
|
||||
proxy_location="RESIDENTIAL",
|
||||
)
|
||||
```
|
||||
|
||||
2. **Some CAPTCHAs can be solved**: Skyvern's AI can solve simple image-based challenges
|
||||
|
||||
3. **Browser profiles help**: Persistent browser state reduces CAPTCHA frequency:
|
||||
|
||||
```python
|
||||
result = await client.login(
|
||||
credential_type="skyvern",
|
||||
url="https://portal.example.com/login",
|
||||
credential_id="cred_xyz789",
|
||||
browser_profile_id="bp_abc123",
|
||||
)
|
||||
```
|
||||
|
||||
4. **For persistent CAPTCHAs**: Contact [support@skyvern.com](mailto:support@skyvern.com) for enterprise CAPTCHA solutions
|
||||
|
||||
---
|
||||
|
||||
### SSO/OAuth redirects
|
||||
|
||||
**Symptoms:** Task fails when encountering "Sign in with Google/Microsoft" or similar SSO flows.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Prefer direct credentials**: SSO flows involve multiple domains and are harder to automate. If possible, use direct username/password login.
|
||||
|
||||
2. **For required SSO**: Use browser sessions to maintain authentication state:
|
||||
|
||||
```python
|
||||
# First run: Complete SSO manually or with Skyvern
|
||||
result = await client.run_task(
|
||||
url="https://portal.example.com/login",
|
||||
prompt="Log in using Google SSO",
|
||||
browser_session_id="bs_xyz789", # Persistent session
|
||||
)
|
||||
|
||||
# Subsequent runs: Reuse the authenticated session
|
||||
result = await client.run_task(
|
||||
url="https://portal.example.com/dashboard",
|
||||
prompt="Navigate to reports",
|
||||
browser_session_id="bs_xyz789",
|
||||
)
|
||||
```
|
||||
|
||||
3. **Check for direct login options**: Many sites offer traditional login alongside SSO (often under "Other login options")
|
||||
|
||||
---
|
||||
|
||||
### Multi-step login flows
|
||||
|
||||
**Symptoms:** Task enters username but fails to proceed to password page, or misses subsequent steps.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Increase `max_steps`**: Multi-step logins require more navigation:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
url="https://portal.example.com/login",
|
||||
prompt="Log in with my credentials",
|
||||
max_steps=15, # Default is 10
|
||||
)
|
||||
```
|
||||
|
||||
2. **Use explicit prompts**: Guide Skyvern through the steps:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
url="https://portal.example.com/login",
|
||||
prompt="""
|
||||
1. Enter the username and click Next
|
||||
2. Wait for the password page to load
|
||||
3. Enter the password and click Sign In
|
||||
4. If 2FA is required, enter the code
|
||||
""",
|
||||
)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
For login flows with credentials, use the `login()` method, which handles credential retrieval and 2FA automatically. Use `run_task()` only for general automation without credential management.
|
||||
</Tip>
|
||||
|
||||
3. **Review recordings**: Watch the recording artifact to see exactly where the flow breaks
|
||||
|
||||
---
|
||||
|
||||
## Debugging checklist
|
||||
|
||||
Use this checklist to systematically debug login failures:
|
||||
|
||||
<Accordion title="Step-by-step debugging process">
|
||||
|
||||
**1. Check run status**
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
Look at `status` and `failure_reason`.
|
||||
|
||||
**2. Review the recording**
|
||||
|
||||
Download the recording artifact and watch where the automation fails:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=recording" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
**3. Check the final screenshot**
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=screenshot_final" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
**4. Verify credential access**
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/YOUR_CREDENTIAL_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
**5. For 2FA issues, check code history**
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_IDENTIFIER" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
|
||||
**6. Review LLM reasoning**
|
||||
|
||||
Check `llm_request` and `llm_response` artifacts to understand what the AI was thinking.
|
||||
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Error messages reference
|
||||
|
||||
| Error | Meaning | Fix |
|
||||
|-------|---------|-----|
|
||||
| `FailedToGetTOTPVerificationCode` | HTTP request to `totp_url` failed | Check endpoint availability and response format |
|
||||
| `NoTOTPVerificationCodeFound` | Polling timed out without receiving code | Ensure codes are pushed or endpoint returns codes |
|
||||
| `TOTPExpiredError` | Code became invalid during entry | Usually auto-resolved on retry; check timing pipeline |
|
||||
| `CredentialParameterNotFoundError` | Referenced credential parameter not found | Verify credential ID and parameter configuration |
|
||||
| `CredentialParameterParsingError` | Failed to parse credential data | Check credential format matches expected schema |
|
||||
| `CustomCredentialConfigurationError` | Custom vault service misconfigured | Verify API base URL and token are set correctly |
|
||||
|
||||
---
|
||||
|
||||
## Getting help
|
||||
|
||||
If you're stuck after trying the above solutions, contact Skyvern support with:
|
||||
|
||||
1. **Run ID**: The `run_id` from your failed run
|
||||
2. **Recording**: Download and attach the recording artifact
|
||||
3. **Description**: What you expected vs. what happened
|
||||
4. **Target site**: The URL you're trying to automate (if not confidential)
|
||||
|
||||
Contact [support@skyvern.com](mailto:support@skyvern.com) or join our [Discord](https://discord.gg/skyvern) for community help.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
|
||||
Review credential setup
|
||||
</Card>
|
||||
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
|
||||
Configure two-factor authentication
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,407 @@
|
||||
---
|
||||
title: Frequently Asked Questions
|
||||
subtitle: Common questions and answers from the Skyvern community
|
||||
description: Answers to common Skyvern questions covering troubleshooting failed tasks, workflow parameters, credentials, scheduling, proxy configuration, API polling, data extraction, and LLM model selection.
|
||||
slug: developers/debugging/faq
|
||||
keywords:
|
||||
- FAQ
|
||||
- common questions
|
||||
- troubleshooting
|
||||
- rate limit
|
||||
- model selection
|
||||
- polling
|
||||
- concurrent runs
|
||||
- community
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Why did my task fail or terminate?">
|
||||
Check these in order:
|
||||
|
||||
1. **Run status**: Use `get_run(run_id)` to see the status and `failure_reason`
|
||||
2. **Timeline**: Use `get_run_timeline(run_id)` to find which block failed
|
||||
3. **Artifacts**: Check `screenshot_final` to see where it stopped, and `recording` to watch what happened
|
||||
|
||||
Common causes:
|
||||
- **`terminated`**: The AI couldn't complete the goal (CAPTCHA, login blocked, element not found)
|
||||
- **`timed_out`**: Exceeded `max_steps`. Increase it or simplify the task
|
||||
- **`failed`**: System error (browser crash, network failure)
|
||||
|
||||
See the [Troubleshooting Guide](/developers/debugging/troubleshooting-guide) for detailed steps.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why is the AI clicking the wrong element?">
|
||||
Multiple similar elements on the page can confuse the AI. Fix this by:
|
||||
|
||||
1. **Add visual context**: "Click the **blue** Submit button at the **bottom** of the form"
|
||||
2. **Reference surrounding text**: "Click Download in the row that says 'January 2024'"
|
||||
3. **Be specific about position**: "Click the first result" or "Click the link in the header"
|
||||
|
||||
Check the `llm_response_parsed` artifact to see what action the AI decided to take.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why is my task timing out?">
|
||||
Tasks time out when they exceed `max_steps` (default: 50). This happens when:
|
||||
|
||||
- The task is too complex for the step limit
|
||||
- The AI gets stuck in a navigation loop
|
||||
- Missing completion criteria causes infinite attempts
|
||||
|
||||
**Fixes:**
|
||||
- Increase `max_steps` in your task parameters
|
||||
- Add explicit completion criteria: "COMPLETE when you see 'Order confirmed'"
|
||||
- Break complex tasks into multiple workflow blocks
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why can't Skyvern find an element on the page?">
|
||||
Elements may not be detected if they:
|
||||
|
||||
- Load dynamically after the page appears
|
||||
- Are inside an iframe
|
||||
- Require scrolling to become visible
|
||||
- Use unusual rendering (canvas, shadow DOM)
|
||||
|
||||
**Fixes:**
|
||||
- Add `max_screenshot_scrolls` to capture lazy-loaded content
|
||||
- Describe elements visually rather than by technical properties
|
||||
- Add explicit wait or scroll instructions in your prompt
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why is the extracted data wrong or incomplete?">
|
||||
Check the `screenshot_final` artifact to verify the AI ended on the right page.
|
||||
|
||||
Common causes:
|
||||
- Prompt was ambiguous about what to extract
|
||||
- `data_extraction_schema` descriptions weren't specific enough
|
||||
- Multiple similar elements and the AI picked the wrong one
|
||||
|
||||
**Fixes:**
|
||||
- Add specific descriptions: `"description": "The price in USD, without currency symbol"`
|
||||
- Add visual hints: "The price is displayed in bold below the product title"
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
<Accordion title="How do I pass parameters to a workflow?">
|
||||
Define parameters in the workflow editor, then pass them when starting a run:
|
||||
|
||||
```python
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wpid_123456",
|
||||
parameters={
|
||||
"url": "https://example.com",
|
||||
"username": "user@example.com"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
Parameters are available in prompts using `{{ parameter_name }}` syntax. See [Workflow Parameters](/cloud/building-workflows/add-parameters) for details.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I use credentials in a workflow?">
|
||||
1. **Store credentials**: Go to Settings > Credentials and add your login
|
||||
2. **Reference in workflow**: Select the credential in the Login block's credential dropdown
|
||||
3. **Never hardcode**: Don't put passwords directly in prompts
|
||||
|
||||
The AI will automatically fill the credential fields when it encounters a login form. See [Credentials](/sdk-reference/credentials) for setup instructions.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Can I run workflows on a schedule?">
|
||||
Yes. Skyvern has built-in cron-based scheduling for workflows. You define a cron expression and timezone, and Skyvern triggers the workflow automatically at each interval.
|
||||
|
||||
- **Cloud UI**: Create and manage schedules from the [Schedules page](/cloud/building-workflows/scheduling)
|
||||
- **API**: Use the [scheduling API](/cloud/building-workflows/run-from-code#create-a-schedule) to create, update, enable/disable, and delete schedules programmatically
|
||||
|
||||
Scheduled runs appear in [Run History](/cloud/viewing-results/run-history) with a calendar icon badge. Set up a [webhook](/developers/going-to-production/webhooks) to get notified when scheduled runs complete.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why isn't my workflow using the parameter values I passed?">
|
||||
Make sure you're using the parameter placeholder syntax correctly:
|
||||
|
||||
- **Correct:** `{{ parameter_name }}`
|
||||
- **Wrong:** `{parameter_name}` or `$parameter_name`
|
||||
|
||||
Also verify:
|
||||
- The parameter name matches exactly (case-sensitive)
|
||||
- The parameter is defined in the workflow's parameter list
|
||||
- You're passing the parameter when starting the run, not after
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I run workflows sequentially with the same credentials?">
|
||||
Use the "Run Sequentially" option with a credential key:
|
||||
|
||||
1. Enable "Run Sequentially" in workflow settings
|
||||
2. Set the sequential key to your credential identifier
|
||||
3. Skyvern will queue runs that share the same credential
|
||||
|
||||
This prevents concurrent logins that could trigger security blocks.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
<Accordion title="Where do I find my API key?">
|
||||
Go to [Settings](https://app.skyvern.com/settings) in the Skyvern Cloud UI. Your API key is displayed there.
|
||||
|
||||
For local installations, run `skyvern init` to generate a local API key, which will be saved in your `.env` file.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I change the LLM model?">
|
||||
**Cloud:** The model is managed by Skyvern. Contact support for custom model requirements.
|
||||
|
||||
**Self-hosted:** Run `skyvern init llm` to reconfigure, or set these environment variables:
|
||||
- `LLM_KEY`: Primary model (e.g., `OPENAI_GPT5_5`, `ANTHROPIC_CLAUDE4.7_OPUS`)
|
||||
- `SECONDARY_LLM_KEY`: Optional lightweight model for faster operations
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I configure proxy settings?">
|
||||
Set `proxy_location` when running a task:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
prompt="...",
|
||||
url="https://example.com",
|
||||
proxy_location="RESIDENTIAL_US" # or RESIDENTIAL_ISP for static IPs
|
||||
)
|
||||
```
|
||||
|
||||
Available locations include `RESIDENTIAL_US`, `RESIDENTIAL_UK`, `RESIDENTIAL_ISP`, and more. Use `RESIDENTIAL_ISP` for sites that require consistent IP addresses.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Can I increase the max steps limit beyond 75?">
|
||||
Yes. Contact support to increase the limit for your account. Higher limits may incur additional costs.
|
||||
|
||||
Alternatively, break complex tasks into multiple workflow blocks, each with its own step budget.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## API & Integration
|
||||
|
||||
<Accordion title="How do I poll for task completion?">
|
||||
Check the run status in a loop:
|
||||
|
||||
```python
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
await asyncio.sleep(5)
|
||||
```
|
||||
|
||||
Or use [webhooks](/developers/going-to-production/webhooks) to get notified when runs complete without polling.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Where can I find extracted data after a run completes?">
|
||||
The extracted data is in `run.output`:
|
||||
|
||||
```python
|
||||
run = await client.get_run(run_id)
|
||||
print(run.output) # {"field1": "value1", "field2": "value2"}
|
||||
```
|
||||
|
||||
For downloaded files, check `run.downloaded_files` which contains signed URLs.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I get the recording URL from the API?">
|
||||
The recording URL is included in the run response:
|
||||
|
||||
```python
|
||||
run = await client.get_run(run_id)
|
||||
print(run.recording_url) # https://skyvern-artifacts.s3.amazonaws.com/.../recording.webm
|
||||
```
|
||||
|
||||
Note: Signed URLs expire after 24 hours. Request fresh URLs if expired.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I trigger a workflow via API?">
|
||||
Use the `run_workflow` method:
|
||||
|
||||
```python
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wpid_123456",
|
||||
parameters={"key": "value"}
|
||||
)
|
||||
print(result.run_id) # wr_789012
|
||||
```
|
||||
|
||||
The workflow starts asynchronously. Poll the run status or configure a webhook to track completion.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Authentication & Credentials
|
||||
|
||||
<Accordion title="Why is my login failing?">
|
||||
Check these common causes:
|
||||
|
||||
1. **Credentials expired**: Verify username/password in your credential store
|
||||
2. **CAPTCHA appeared**: Use a browser profile with an existing session
|
||||
3. **MFA required**: Configure TOTP if the site requires 2FA
|
||||
4. **Site detected automation**: Use `RESIDENTIAL_ISP` proxy for trusted IPs
|
||||
|
||||
Watch the `recording` artifact to see exactly what happened during login.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I handle CAPTCHA?">
|
||||
Options to bypass CAPTCHAs:
|
||||
|
||||
1. **Browser profile**: Create a profile with an authenticated session that skips login entirely
|
||||
2. **Human interaction block**: Pause the workflow for manual CAPTCHA solving
|
||||
3. **Residential proxy**: Use `RESIDENTIAL_ISP` for static IPs that sites trust more
|
||||
|
||||
Skyvern has built-in CAPTCHA solving for common types, but some sites use advanced anti-bot measures.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I set up 2FA/TOTP?">
|
||||
1. Go to Settings > Credentials
|
||||
2. Create a new TOTP credential with your authenticator secret
|
||||
3. Reference the TOTP credential in your workflow's login block
|
||||
|
||||
The AI will automatically fetch and enter the TOTP code when it encounters a 2FA prompt. See [TOTP Setup](/developers/credentials/totp) for detailed instructions.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I handle email OTP verification?">
|
||||
Email OTP requires an external integration:
|
||||
|
||||
1. Set up an email listener (Zapier, custom webhook, etc.)
|
||||
2. When the OTP arrives, send it back to Skyvern via the API
|
||||
3. Use a Human Interaction block to wait for the code
|
||||
|
||||
Alternatively, check if the site supports TOTP authenticators, which Skyvern handles natively.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Browser & Proxy
|
||||
|
||||
<Accordion title="Why is the site blocking Skyvern?">
|
||||
Sites may detect automation through:
|
||||
|
||||
- IP reputation (datacenter IPs are often blocked)
|
||||
- Browser fingerprinting
|
||||
- Rate limiting
|
||||
|
||||
**Fixes:**
|
||||
- Use `RESIDENTIAL_ISP` proxy for consistent, trusted IPs
|
||||
- Create a browser profile with an existing authenticated session
|
||||
- Slow down requests by adding explicit waits in your prompt
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I persist cookies across runs?">
|
||||
Use browser profiles:
|
||||
|
||||
1. Create a browser profile in Settings > Browser Profiles
|
||||
2. Log in manually or via a workflow
|
||||
3. Reference the `browser_profile_id` in subsequent runs
|
||||
|
||||
The profile preserves cookies, localStorage, and session state across runs.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Can I connect Skyvern to my local browser?">
|
||||
Yes, for self-hosted installations:
|
||||
|
||||
```bash
|
||||
skyvern init # Choose "connect to existing Chrome" option
|
||||
skyvern run server
|
||||
```
|
||||
|
||||
This connects to Chrome running on your machine, useful for debugging or accessing internal tools.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why am I getting a 504 timeout when creating browser sessions?">
|
||||
This usually indicates high load or network issues:
|
||||
|
||||
- Wait a few seconds and retry
|
||||
- Check your rate limits
|
||||
- For self-hosted: verify your infrastructure has sufficient resources
|
||||
|
||||
If persistent, contact support with your run IDs.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Self-Hosting & Deployment
|
||||
|
||||
<Accordion title="What are the requirements for self-hosting Skyvern?">
|
||||
- Python 3.11, 3.12, or 3.13
|
||||
- PostgreSQL database
|
||||
- An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Ollama)
|
||||
- Docker (optional, for containerized deployment)
|
||||
|
||||
Run `skyvern init` for an interactive setup wizard. See the [Quickstart](/developers/getting-started/quickstart) for full instructions.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I update my self-hosted Skyvern instance?">
|
||||
```bash
|
||||
pip install --upgrade skyvern
|
||||
alembic upgrade head # Run database migrations
|
||||
skyvern run server # Restart the server
|
||||
```
|
||||
|
||||
For Docker deployments, pull the latest image and restart your containers.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I configure a custom LLM provider?">
|
||||
Set these environment variables:
|
||||
|
||||
```bash
|
||||
ENABLE_OPENAI=true # or ENABLE_ANTHROPIC, ENABLE_AZURE, etc.
|
||||
OPENAI_API_KEY=sk-...
|
||||
LLM_KEY=OPENAI_GPT5_5
|
||||
```
|
||||
|
||||
Skyvern supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, and Ollama. Run `skyvern init llm` for guided configuration.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Billing & Pricing
|
||||
|
||||
<Accordion title="How is pricing calculated?">
|
||||
Pricing depends on your plan:
|
||||
|
||||
- **Pay-as-you-go**: Charged per step or per task completion
|
||||
- **Enterprise**: Custom pricing based on volume
|
||||
|
||||
View your usage and billing at [Settings > Billing](https://app.skyvern.com/billing).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Why does it say insufficient balance when I have credit?">
|
||||
Credits may be reserved for in-progress runs. Check:
|
||||
|
||||
1. Active runs that haven't completed yet
|
||||
2. Failed runs that consumed partial credit
|
||||
3. Pending charges that haven't settled
|
||||
|
||||
Wait for active runs to complete, then check your balance again.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I get invoices for my payments?">
|
||||
Go to [Settings > Billing](https://app.skyvern.com/billing) to download invoices. For custom invoice requirements (company name, VAT, etc.), contact support.
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Still have questions?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Troubleshooting Guide"
|
||||
icon="wrench"
|
||||
href="/developers/debugging/troubleshooting-guide"
|
||||
>
|
||||
Step-by-step debugging for failed runs
|
||||
</Card>
|
||||
<Card
|
||||
title="Contact Support"
|
||||
icon="headset"
|
||||
href="https://app.skyvern.com"
|
||||
>
|
||||
Chat with us via the support widget
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: Observability with Laminar
|
||||
subtitle: Add observability to your Skyvern automations with Laminar
|
||||
description: Integrate Laminar observability into Skyvern to capture traces of automation runs, track LLM call latency and token usage, monitor failure rates, and debug performance across tasks and workflows.
|
||||
slug: developers/debugging/observability-with-laminar
|
||||
keywords:
|
||||
- Laminar
|
||||
- traces
|
||||
- LLM latency
|
||||
- token usage
|
||||
- failure rate
|
||||
- monitoring
|
||||
- performance
|
||||
- observability
|
||||
---
|
||||
|
||||
[Laminar](https://www.lmnr.ai/) is an observability platform for AI applications. When integrated with Skyvern, it captures traces of your automation runs in Laminar's dashboard. What you see depends on how you're running Skyvern:
|
||||
|
||||
- **Skyvern Cloud (via SDK)**: Laminar wraps the `run_task` / `run_workflow` call, so you get a trace span around the API request and response: latency, status, errors, and the returned output.
|
||||
- **Self-hosted**: Skyvern's server can export full traces to Laminar, including every LLM call (prompts, responses, token usage), browser actions, and workflow step execution. See [self-hosted tracing setup](#self-hosted-tracing-setup) below.
|
||||
|
||||
<Tip>
|
||||
Laminar traces complement [artifacts](/developers/debugging/using-artifacts). Use artifacts for per-run debugging (screenshots, recordings, logs) and Laminar for tracking patterns across runs (failure rates, response times, and which tasks are slowest).
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
This guide is also available in the [Laminar documentation](https://docs.lmnr.ai/tracing/integrations/skyvern).
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Laminar integration requires a Skyvern SDK and the Laminar SDK:
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
pip install skyvern 'lmnr[all]'
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npm install @skyvern/client @lmnr-ai/lmnr
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
You will also need:
|
||||
- A **Skyvern API key**: get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/)
|
||||
- A **Laminar API key**: sign up at [lmnr.ai](https://www.lmnr.ai/) and create a project
|
||||
|
||||
---
|
||||
|
||||
## Set up environment variables
|
||||
|
||||
Add both keys to your `.env` file:
|
||||
|
||||
```bash .env
|
||||
SKYVERN_API_KEY=your-skyvern-api-key
|
||||
LMNR_PROJECT_API_KEY=your-laminar-api-key
|
||||
```
|
||||
|
||||
<Frame>
|
||||
<video
|
||||
autoPlay
|
||||
controls
|
||||
muted
|
||||
playsInline
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="/images/laminar-keys.mp4"
|
||||
></video>
|
||||
</Frame>
|
||||
|
||||
---
|
||||
|
||||
## Run a traced task
|
||||
|
||||
This example scrapes the top 3 posts from Hacker News with Laminar tracing enabled. Call `Laminar.initialize()` before any Skyvern calls; it reads `LMNR_PROJECT_API_KEY` from your environment automatically.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
import asyncio
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
|
||||
from lmnr import Laminar
|
||||
Laminar.initialize()
|
||||
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
async def main():
|
||||
result = await client.run_task(
|
||||
prompt="Get the title and URL of the top 3 posts on Hacker News.",
|
||||
url="https://news.ycombinator.com",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(f"Status: {result.status}")
|
||||
print(f"Output: {result.output}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Laminar } from "@lmnr-ai/lmnr";
|
||||
Laminar.initialize();
|
||||
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const client = new Skyvern({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
async function main() {
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the title and URL of the top 3 posts on Hacker News.",
|
||||
url: "https://news.ycombinator.com",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(`Status: ${result.status}`);
|
||||
console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Expected output:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed",
|
||||
"output": {
|
||||
"posts": [
|
||||
{"title": "Zig – Type Resolution Redesign and Language Changes", "url": "https://ziglang.org/devlog/2026/..."},
|
||||
{"title": "Create value for others and don't worry about the returns", "url": "https://geohot.github.io/..."},
|
||||
{"title": "U+237C ⍼ Is Azimuth", "url": "https://ionathan.ch/2026/02/16/angzarr.html"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The task runs, the output is returned, and the full trace (every HTTP call, timing, and payload) appears in your Laminar dashboard.
|
||||
|
||||
<Note>
|
||||
**Python only:** You will see a `ForgeApp is not initialized` error in stderr on startup. This is harmless; `lmnr[all]` tries to instrument Skyvern's server-side internals, which aren't present when using the client SDK. Your traces still work correctly.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
**Python only:** `LaminarLiteLLMCallback` is deprecated and unnecessary. Laminar instruments LiteLLM directly, so no callback setup is needed.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## What traces capture
|
||||
|
||||
What shows up in Laminar depends on your setup.
|
||||
|
||||
### Skyvern Cloud (via SDK)
|
||||
|
||||
When calling `run_task` or `run_workflow` through the SDK, Laminar traces the client-side call:
|
||||
|
||||
| Trace data | What it shows |
|
||||
|------------|---------------|
|
||||
| API request/response | The full round-trip to Skyvern's API (status, latency, payload size) |
|
||||
| Task output | The extracted data or completion result |
|
||||
| Errors | HTTP errors, timeouts, and task failures |
|
||||
|
||||
This is useful for monitoring how your application interacts with Skyvern: tracking which tasks fail, how long they take, and what outputs you're getting back.
|
||||
|
||||
### Self-hosted
|
||||
|
||||
When running Skyvern on your own infrastructure, you get deep server-side traces by configuring Laminar in Skyvern's environment. This gives you visibility into everything happening inside the agent:
|
||||
|
||||
| Trace data | What it shows |
|
||||
|------------|---------------|
|
||||
| LLM interactions | Every prompt sent to the model and its response, including token counts |
|
||||
| Browser actions | Each click, type, and navigation the agent performed |
|
||||
| Workflow steps | Sequential block execution and data passed between blocks |
|
||||
| Image tracing | Screenshots sent to the LLM for analysis |
|
||||
| Performance metrics | Latency and cost per LLM call |
|
||||
| Errors | Exceptions at any layer: LLM, browser, workflow engine |
|
||||
|
||||
---
|
||||
|
||||
## Self-hosted tracing setup
|
||||
|
||||
If you're running Skyvern on your own infrastructure, add these to your server's environment:
|
||||
|
||||
```bash .env
|
||||
LMNR_PROJECT_API_KEY=your-laminar-api-key
|
||||
```
|
||||
|
||||
Skyvern's server initializes Laminar at startup, which auto-instruments LiteLLM to capture every LLM call, token count, and cost. No manual callback setup is needed.
|
||||
|
||||
If you're running a self-hosted Laminar instance, also set the base URL and ports:
|
||||
|
||||
```bash .env
|
||||
LMNR_PROJECT_API_KEY=your-laminar-api-key
|
||||
LMNR_BASE_URL=http://localhost
|
||||
LMNR_GRPC_PORT=8011
|
||||
LMNR_HTTP_PORT=8010
|
||||
```
|
||||
|
||||
No code changes needed. Once the env vars are set, traces appear in your Laminar project automatically.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Using Artifacts"
|
||||
icon="file-lines"
|
||||
href="/developers/debugging/using-artifacts"
|
||||
>
|
||||
Per-run recordings, screenshots, logs, and network data
|
||||
</Card>
|
||||
<Card
|
||||
title="Troubleshooting Guide"
|
||||
icon="wrench"
|
||||
href="/developers/debugging/troubleshooting-guide"
|
||||
>
|
||||
Common issues and how to fix them
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,386 @@
|
||||
---
|
||||
title: Troubleshooting Guide
|
||||
subtitle: Common issues, step timeline, and when to adjust what
|
||||
description: Diagnose and fix common Skyvern run failures using the step timeline, artifacts, and run status. Covers issues like wrong output, timeouts, CAPTCHA blocks, login failures, and element detection problems.
|
||||
slug: developers/debugging/troubleshooting-guide
|
||||
keywords:
|
||||
- step timeline
|
||||
- wrong output
|
||||
- timeout
|
||||
- CAPTCHA block
|
||||
- login failure
|
||||
- element detection
|
||||
- action failure
|
||||
- diagnosis
|
||||
---
|
||||
|
||||
When a run fails or produces unexpected results, this guide helps you identify the cause and fix it.
|
||||
|
||||
## Quick debugging checklist
|
||||
|
||||
<Frame>
|
||||
<img src="/images/debugging-checklist.png" alt="Skyvern Debugging Checklist" />
|
||||
</Frame>
|
||||
|
||||
<Steps>
|
||||
<Step title="Check run status">
|
||||
Call `get_run(run_id)` and check `status` and `failure_reason`
|
||||
</Step>
|
||||
<Step title="Find the failed step">
|
||||
Call `get_run_timeline(run_id)` to see which block failed
|
||||
</Step>
|
||||
<Step title="Inspect artifacts">
|
||||
Check `screenshot_final` to see where it stopped, `recording` to watch what happened
|
||||
</Step>
|
||||
<Step title="Determine the fix">
|
||||
Adjust prompt, parameters, or file a bug based on what you find
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
**Key artifacts to check:**
|
||||
- `screenshot_final`: Final page state
|
||||
- `recording`: Video of what happened
|
||||
- `llm_response_parsed`: What the AI decided to do
|
||||
- `visible_elements_tree`: What elements were detected
|
||||
- `har`: Network requests if something failed to load
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check the run
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
print(f"Status: {run.status}")
|
||||
print(f"Failure reason: {run.failure_reason}")
|
||||
print(f"Step count: {run.step_count}")
|
||||
print(f"Output: {run.output}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { SkyvernClient } from "@skyvern/client";
|
||||
|
||||
const client = new SkyvernClient({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
console.log(`Status: ${run.status}`);
|
||||
console.log(`Failure reason: ${run.failure_reason}`);
|
||||
console.log(`Step count: ${run.step_count}`);
|
||||
console.log(`Output: ${JSON.stringify(run.output)}`);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
| jq '{status, failure_reason, step_count, output}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Status | What it means | Likely cause |
|
||||
|--------|---------------|--------------|
|
||||
| `completed` | Run finished, but output may be wrong | Prompt interpretation issue |
|
||||
| `failed` | System error | Browser crash, network failure |
|
||||
| `terminated` | AI gave up | Login blocked, CAPTCHA, page unavailable |
|
||||
| `timed_out` | Exceeded `max_steps` | Task too complex, or AI got stuck |
|
||||
| `canceled` | Manually stopped | N/A |
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read the step timeline
|
||||
|
||||
The timeline shows each block and action in execution order.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
timeline = await client.get_run_timeline(run_id)
|
||||
|
||||
for item in timeline:
|
||||
if item.type == "block":
|
||||
block = item.block
|
||||
print(f"Block: {block.label}")
|
||||
print(f" Status: {block.status}")
|
||||
print(f" Duration: {block.duration}s")
|
||||
if block.failure_reason:
|
||||
print(f" Failure: {block.failure_reason}")
|
||||
for action in block.actions:
|
||||
print(f" Action: {action.action_type} -> {action.status}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const timeline = await client.getRunTimeline(runId);
|
||||
|
||||
for (const item of timeline) {
|
||||
if (item.type === "block") {
|
||||
const block = item.block;
|
||||
console.log(`Block: ${block.label}`);
|
||||
console.log(` Status: ${block.status}`);
|
||||
console.log(` Duration: ${block.duration}s`);
|
||||
if (block.failure_reason) {
|
||||
console.log(` Failure: ${block.failure_reason}`);
|
||||
}
|
||||
for (const action of block.actions || []) {
|
||||
console.log(` Action: ${action.action_type} -> ${action.status}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/timeline" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Inspect artifacts
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
artifacts = await client.get_run_artifacts(
|
||||
run_id,
|
||||
artifact_type=["screenshot_final", "llm_response_parsed", "skyvern_log"]
|
||||
)
|
||||
|
||||
for a in artifacts:
|
||||
print(f"{a.artifact_type}: {a.signed_url}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const artifacts = await client.getRunArtifacts(runId, {
|
||||
artifact_type: ["screenshot_final", "llm_response_parsed", "skyvern_log"]
|
||||
});
|
||||
|
||||
for (const a of artifacts) {
|
||||
console.log(`${a.artifact_type}: ${a.signed_url}`);
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts?artifact_type=screenshot_final&artifact_type=llm_response_parsed&artifact_type=skyvern_log" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
| jq '.[] | "\(.artifact_type): \(.signed_url)"'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
See [Using Artifacts](/developers/debugging/using-artifacts) for the full list of artifact types.
|
||||
|
||||
---
|
||||
|
||||
## Common issues and fixes
|
||||
|
||||
### Run Status Issues
|
||||
|
||||
<Accordion title="Run completed but output is wrong">
|
||||
**Symptom:** Status is `completed`, but the extracted data is incorrect or incomplete.
|
||||
|
||||
**Check:** `screenshot_final` (right page?) and `llm_response_parsed` (right elements?)
|
||||
|
||||
**Fix:**
|
||||
- Add specific descriptions in your schema: `"description": "The price in USD, without currency symbol"`
|
||||
- Add visual hints: "The price is displayed in bold below the product title"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Run timed out">
|
||||
**Symptom:** Status is `timed_out`.
|
||||
|
||||
**Check:** `recording` (stuck in a loop?) and `step_count` (how many steps?)
|
||||
|
||||
**Fix:**
|
||||
- Increase `max_steps` if the task genuinely needs more steps
|
||||
- Add explicit completion criteria: "COMPLETE when you see 'Order confirmed'"
|
||||
- Break complex tasks into multiple workflow blocks
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Run stuck in queued state">
|
||||
**Symptom:** Run stays in `queued` status and never starts.
|
||||
|
||||
**Likely causes:** Concurrency limit hit, sequential run lock, or high platform load.
|
||||
|
||||
**Fix:**
|
||||
- Wait for other runs to complete
|
||||
- Check your plan's concurrency limits in Settings
|
||||
- If using "Run Sequentially" with credentials, ensure prior runs finish
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="504 Gateway Timeout on browser session">
|
||||
**Symptom:** Getting `504 Gateway Timeout` errors when creating browser sessions.
|
||||
|
||||
**Fix:**
|
||||
- Retry after a few seconds; usually transient
|
||||
- For self-hosted: check infrastructure resources
|
||||
- If persistent, contact support with your run IDs
|
||||
</Accordion>
|
||||
|
||||
### Element & Interaction Issues
|
||||
|
||||
<Accordion title="AI clicked the wrong element">
|
||||
**Symptom:** Recording shows the AI clicking something other than intended.
|
||||
|
||||
**Check:** `visible_elements_tree` (element detected?) and `llm_prompt` (target described clearly?)
|
||||
|
||||
**Fix:**
|
||||
- Add distinguishing details: "Click the **blue** Submit button at the **bottom** of the form"
|
||||
- Reference surrounding text: "Click Download in the row that says 'January 2024'"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Element not found">
|
||||
**Symptom:** `failure_reason` mentions an element couldn't be found.
|
||||
|
||||
**Check:** `screenshot_final` (element visible?) and `visible_elements_tree` (element detected?)
|
||||
|
||||
**Likely causes:** Dynamic loading, iframe, below the fold, unusual rendering (canvas, shadow DOM)
|
||||
|
||||
**Fix:**
|
||||
- Add `max_screenshot_scrolls` to capture lazy-loaded content
|
||||
- Describe elements visually rather than by technical properties
|
||||
- Add wait or scroll instructions in your prompt
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Date fields entering wrong values">
|
||||
**Symptom:** Dates entered in wrong format (MM/DD vs DD/MM) or wrong date entirely.
|
||||
|
||||
**Check:** `recording` (how did AI interact with the date picker?)
|
||||
|
||||
**Fix:**
|
||||
- Specify exact format: "Enter the date as **15/01/2024** (DD/MM/YYYY format)"
|
||||
- For date pickers: "Click the date field, then select January 15, 2024 from the calendar"
|
||||
- If site auto-formats: "Type 01152024 and let the field format it"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Address autocomplete cycling or wrong selection">
|
||||
**Symptom:** AI keeps clicking through address suggestions in a loop, or selects wrong address.
|
||||
|
||||
**Check:** `recording` (is autocomplete dropdown appearing?)
|
||||
|
||||
**Fix:**
|
||||
- Specify selection: "Type '123 Main St' and select the first suggestion showing 'New York, NY'"
|
||||
- Disable autocomplete: "Type the full address without using autocomplete suggestions"
|
||||
- Break into steps: "Enter street address, wait for dropdown, select the matching suggestion"
|
||||
</Accordion>
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
<Accordion title="Login failed">
|
||||
**Symptom:** Status is `terminated` with login-related failure reason.
|
||||
|
||||
**Check:** `screenshot_final` (error message?) and `recording` (fields filled correctly?)
|
||||
|
||||
**Likely causes:** Expired credentials, CAPTCHA, MFA required, automation detected
|
||||
|
||||
**Fix:**
|
||||
- Verify credentials in your credential store
|
||||
- Use `RESIDENTIAL_ISP` proxy for more stable IPs
|
||||
- Configure TOTP if MFA is required
|
||||
- Use a browser profile with an existing session
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="CAPTCHA blocked the run">
|
||||
**Symptom:** `failure_reason` mentions CAPTCHA.
|
||||
|
||||
**Fix options:**
|
||||
1. **Browser profile**: Use an authenticated session that skips login
|
||||
2. **Human interaction block**: Pause for manual CAPTCHA solving
|
||||
3. **Different proxy**: Use `RESIDENTIAL_ISP` for static IPs sites trust more
|
||||
</Accordion>
|
||||
|
||||
### Data & Output Issues
|
||||
|
||||
<Accordion title="AI hallucinating or inventing data">
|
||||
**Symptom:** Extracted data contains information not on the page.
|
||||
|
||||
**Check:** `screenshot_final` (data visible?) and `llm_response_parsed` (what did AI claim to see?)
|
||||
|
||||
**Fix:**
|
||||
- Add instruction: "Only extract data **visibly displayed** on the page. Return null if not found"
|
||||
- Make schema fields optional where appropriate
|
||||
- Add validation: "If price is not displayed, set price to null instead of guessing"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="File downloads not working">
|
||||
**Symptom:** Files download repeatedly, wrong files, or downloads don't complete.
|
||||
|
||||
**Check:** `recording` (download button clicked correctly?) and `downloaded_files` in response
|
||||
|
||||
**Fix:**
|
||||
- Be specific: "Click the **PDF** download button, not the Excel one"
|
||||
- Add wait time: "Wait for the download to complete"
|
||||
- For multi-step downloads: "Click Download, then select PDF format, then click Confirm"
|
||||
</Accordion>
|
||||
|
||||
### Environment Issues
|
||||
|
||||
<Accordion title="Site showing content in wrong language">
|
||||
**Symptom:** Site displays in unexpected language based on proxy location.
|
||||
|
||||
**Check:** What `proxy_location` is being used? Does site geo-target?
|
||||
|
||||
**Fix:**
|
||||
- Use appropriate proxy: `RESIDENTIAL_US` for English US sites
|
||||
- Add instruction: "If the site asks for language preference, select English"
|
||||
- Set language in URL: `https://example.com/en/`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Workflow gets stuck in a loop">
|
||||
**Symptom:** Recording shows AI repeating the same actions without progressing.
|
||||
|
||||
**Check:** `recording` (what pattern is repeating?) and conditional block exit conditions
|
||||
|
||||
**Fix:**
|
||||
- Add termination: "STOP if you've attempted this action 3 times without success"
|
||||
- Add completion markers: "COMPLETE when you see 'Success' message"
|
||||
- Review loop conditions to ensure exit criteria are achievable
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## When to adjust prompts vs parameters
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Adjust prompt" icon="pen">
|
||||
- AI misunderstood what to do
|
||||
- Clicked wrong element
|
||||
- Ambiguous completion criteria
|
||||
- Extracted wrong data
|
||||
</Card>
|
||||
<Card title="Adjust parameters" icon="sliders">
|
||||
- Timed out → increase `max_steps`
|
||||
- Site blocked → change `proxy_location`
|
||||
- Content didn't load → increase `max_screenshot_scrolls`
|
||||
</Card>
|
||||
<Card title="File a bug" icon="bug">
|
||||
- Visible element not detected
|
||||
- Standard UI patterns don't work
|
||||
- Consistent wrong element despite clear prompts
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Using Artifacts"
|
||||
icon="file-lines"
|
||||
href="/developers/debugging/using-artifacts"
|
||||
>
|
||||
Detailed reference for all artifact types
|
||||
</Card>
|
||||
<Card
|
||||
title="Reliability Tips"
|
||||
icon="shield-check"
|
||||
href="/developers/going-to-production/reliability-tips"
|
||||
>
|
||||
Write prompts that fail less often
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: Using Artifacts
|
||||
subtitle: Access recordings, screenshots, logs, and network data for every run
|
||||
description: Retrieve and inspect artifacts from Skyvern runs including browser recordings, screenshots, AI reasoning logs, DOM element trees, network HAR files, and Playwright traces to debug failures and unexpected results.
|
||||
slug: developers/debugging/using-artifacts
|
||||
keywords:
|
||||
- artifact
|
||||
- recording
|
||||
- screenshot
|
||||
- HAR file
|
||||
- Playwright trace
|
||||
- DOM tree
|
||||
- AI reasoning log
|
||||
- network data
|
||||
- generated code
|
||||
---
|
||||
|
||||
When a Skyvern run fails or produces unexpected results, artifacts are your debugging toolkit. Every run automatically captures what happened: recordings of the browser session, screenshots at each step, the AI's reasoning, and network traffic.
|
||||
|
||||
This page covers how to retrieve artifacts and what each type tells you.
|
||||
|
||||
<Tip>
|
||||
Looking for a specific artifact type? Jump to the [artifact types reference](#artifact-types-reference) to see all available types, then come back here to learn how to retrieve them.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Before you start
|
||||
|
||||
You need a `run_id` to retrieve artifacts. You get this when you [run a task](/running-automations/run-a-task) or workflow.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve artifacts
|
||||
|
||||
Use `get_run_artifacts` with the `run_id` from your task or workflow run:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
artifacts = await client.get_run_artifacts(run_id)
|
||||
|
||||
for artifact in artifacts:
|
||||
print(f"{artifact.artifact_type}: {artifact.signed_url}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { SkyvernClient } from "@skyvern/client";
|
||||
|
||||
const client = new SkyvernClient({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
const artifacts = await client.getRunArtifacts(runId);
|
||||
|
||||
for (const artifact of artifacts) {
|
||||
console.log(`${artifact.artifact_type}: ${artifact.signed_url}`);
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
Signed URLs expire after 24 hours. If a URL has expired, call `get_run_artifacts` again to get fresh URLs. When running Skyvern locally, `signed_url` will be `null`. Access artifacts directly from your local file system instead.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Filter by artifact type
|
||||
|
||||
To get only specific artifact types, pass `artifact_type`:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Get only recordings and final screenshots
|
||||
artifacts = await client.get_run_artifacts(
|
||||
run_id,
|
||||
artifact_type=["recording", "screenshot_final"]
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const artifacts = await client.getRunArtifacts(runId, {
|
||||
artifact_type: ["recording", "screenshot_final"],
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts?artifact_type=recording&artifact_type=screenshot_final" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Artifact types reference
|
||||
|
||||
### Visual artifacts
|
||||
|
||||
These show you what the browser looked like at various points.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `recording` | Full video of the browser session (WebM) | Watch the entire run, see exactly what happened |
|
||||
| `screenshot` | Base screenshot capture | General page state capture |
|
||||
| `screenshot_final` | Screenshot when the run ended | Check the final state (did it end on the right page?) |
|
||||
| `screenshot_action` | Screenshot taken after each action | See the page state after each click, type, or navigation |
|
||||
| `screenshot_llm` | Screenshot sent to the LLM for decision-making | Understand what the AI "saw" when it made each decision |
|
||||
|
||||
**Debugging tip:** If the run failed, start with `screenshot_final` to see where it stopped, then watch the `recording` to see how it got there.
|
||||
|
||||
### AI reasoning artifacts
|
||||
|
||||
These show you why the AI made each decision.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `llm_prompt` | The prompt sent to the LLM | See exactly what instructions the AI received |
|
||||
| `llm_request` | Full request including context | Check if the right context was included |
|
||||
| `llm_response` | Raw LLM response | See the AI's unprocessed output |
|
||||
| `llm_response_parsed` | Parsed response (extracted actions) | Understand what actions the AI decided to take |
|
||||
| `llm_response_rendered` | Parsed response with real URLs | Debug URL targeting issues (see below) |
|
||||
|
||||
**Debugging tip:** If the AI did something unexpected, check `llm_prompt` to see if your prompt was interpreted correctly, then `llm_response_parsed` to see what action it extracted.
|
||||
|
||||
**About `llm_response_rendered`:** Skyvern hashes URLs before sending them to the LLM to reduce token usage and avoid confusing the model with long query strings. The `llm_response_parsed` artifact contains these hashed placeholders (like `{{_a1b2c3}}`), while `llm_response_rendered` shows the same response with actual URLs substituted back in. Use this when you need to verify which exact URL the AI targeted.
|
||||
|
||||
### Page structure artifacts
|
||||
|
||||
These show how Skyvern interpreted the page.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `visible_elements_tree` | DOM tree of visible elements (JSON) | See which elements Skyvern detected |
|
||||
| `visible_elements_tree_trimmed` | Trimmed tree (sent to LLM) | See what the AI could "see" |
|
||||
| `visible_elements_tree_in_prompt` | Element tree as plain text | Read exactly what was embedded in the prompt |
|
||||
| `visible_elements_id_css_map` | CSS selectors for each element | Debug element targeting issues |
|
||||
| `visible_elements_id_frame_map` | Element-to-iframe mapping | Debug elements inside iframes |
|
||||
| `visible_elements_id_xpath_map` | XPath selectors for each element | Alternative element targeting debug |
|
||||
| `hashed_href_map` | Mapping of hashed URLs to original URLs | Decode URL placeholders in LLM responses |
|
||||
| `html` | Generic HTML capture | Inspect page HTML |
|
||||
| `html_scrape` | Full HTML captured during scraping | Inspect the raw page structure |
|
||||
| `html_action` | HTML captured after an action | See how the page changed after each action |
|
||||
|
||||
**Debugging tip:** If the AI couldn't find an element, check `visible_elements_tree` to see if it was detected. If not, the element might be in an iframe, dynamically loaded, or outside the viewport.
|
||||
|
||||
**About the element tree variants:** The `visible_elements_tree` is a JSON structure, while `visible_elements_tree_in_prompt` is the plain-text representation that gets embedded directly into the LLM prompt. The latter is often easier to read when debugging prompt issues. If you're debugging iframe-related problems, `visible_elements_id_frame_map` shows which frame contains each element ID.
|
||||
|
||||
### Log artifacts
|
||||
|
||||
These contain structured execution data.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `skyvern_log` | Formatted execution logs | Read through the run step-by-step |
|
||||
| `skyvern_log_raw` | Raw JSON logs | Parse programmatically for automation |
|
||||
| `browser_console_log` | Browser console output | Debug JavaScript errors on the page |
|
||||
|
||||
**Debugging tip:** `skyvern_log` is human-readable and shows the flow of execution. Start here for an overview before diving into specific artifacts.
|
||||
|
||||
### Network artifacts
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `har` | HTTP Archive (network requests/responses) | Debug API calls, check for failed requests, see response data |
|
||||
| `trace` | Playwright trace file | Replay the session in Playwright Trace Viewer |
|
||||
|
||||
**Debugging tip:** The HAR file captures every network request. If a form submission failed, check the HAR to see if the request was sent and what the server responded.
|
||||
|
||||
### File artifacts
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `script_file` | Generated Playwright scripts | See the code Skyvern would use to repeat this task |
|
||||
|
||||
---
|
||||
|
||||
## Artifact response fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `artifact_id` | string | Unique identifier |
|
||||
| `artifact_type` | string | Type (see tables above) |
|
||||
| `uri` | string | Internal storage path |
|
||||
| `signed_url` | string \| null | Pre-signed URL for downloading |
|
||||
| `task_id` | string \| null | Associated task ID |
|
||||
| `step_id` | string \| null | Associated step ID |
|
||||
| `run_id` | string \| null | Run ID (e.g., `tsk_v2_...`, `wr_...`) |
|
||||
| `workflow_run_id` | string \| null | Workflow run ID |
|
||||
| `workflow_run_block_id` | string \| null | Workflow block ID |
|
||||
| `organization_id` | string | Your organization |
|
||||
| `created_at` | datetime | When created |
|
||||
| `modified_at` | datetime | When modified |
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Troubleshooting Guide"
|
||||
icon="wrench"
|
||||
href="/developers/debugging/troubleshooting-guide"
|
||||
>
|
||||
Common issues and how to fix them
|
||||
</Card>
|
||||
<Card
|
||||
title="Error Handling"
|
||||
icon="triangle-exclamation"
|
||||
href="/developers/going-to-production/error-handling"
|
||||
>
|
||||
Map errors to custom codes for programmatic handling
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Authentication & 2FA
|
||||
subtitle: Log in to any site, including sites with multi-factor authentication
|
||||
description: Skyvern handles logins with stored credentials, TOTP/authenticator codes, email and SMS verification, magic links, and password manager integrations with Bitwarden, 1Password, and Azure Key Vault.
|
||||
slug: developers/features/authentication-and-2fa
|
||||
icon: key
|
||||
keywords:
|
||||
- authentication
|
||||
- login
|
||||
- 2FA
|
||||
- MFA
|
||||
- TOTP
|
||||
- magic link
|
||||
- SSO
|
||||
- Bitwarden
|
||||
- 1Password
|
||||
- Azure Key Vault
|
||||
---
|
||||
|
||||
Most browser automations hit a login wall within the first few seconds. Skyvern handles authentication end-to-end, from simple passwords to multi-factor flows with TOTP codes, email verification, and magic links. Secrets live in your vault and never touch the LLM.
|
||||
|
||||
## What's supported
|
||||
|
||||
**Credential types:** passwords (with optional TOTP secret bundled in), credit cards for checkout automations, and arbitrary secrets or API keys.
|
||||
|
||||
**2FA methods:**
|
||||
|
||||
- **TOTP / authenticator apps** store the secret once and Skyvern generates valid codes on every run.
|
||||
- **Email or SMS codes** can be pushed to Skyvern via API, or you can expose an endpoint that Skyvern polls every 10 seconds until the code arrives.
|
||||
- **Magic links** work the same way: push the one-time login URL and Skyvern detects and follows it automatically.
|
||||
- **Multi-field TOTP** handles split-box layouts (one digit per input) by filling all fields with the same code.
|
||||
|
||||
**Vault integrations:** Bitwarden (Cloud and self-hosted / Vaultwarden), 1Password (via service account token), Azure Key Vault, and a custom HTTP vault option if you want to bring your own service.
|
||||
|
||||
## How credentials stay safe
|
||||
|
||||
When a run needs a credential, Skyvern fetches it from your vault, injects it directly into the browser's form field, and discards it as soon as the field is filled. The value never enters an LLM prompt, never lands in a log line, and never gets written to any persistent Skyvern storage.
|
||||
|
||||
You'll see this in practice: run recordings, action timelines, and LLM prompts show stable placeholder tokens like `BW_PASSWORD`, `BW_USERNAME`, and `BW_TOTP` wherever real credentials were used. The prefix reflects the vault source (`BW_` for Bitwarden, `OP_` for 1Password, `AZ_` for Azure Key Vault, `SK_` for Skyvern's built-in vault) so you can audit which credential fired without the secret ever leaving your vault.
|
||||
|
||||
## Learn more
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Store credentials"
|
||||
href="/developers/credentials/store-credentials"
|
||||
>
|
||||
Create passwords, cards, and secrets. Wire up Bitwarden, 1Password, Azure, or a custom vault.
|
||||
</Card>
|
||||
<Card
|
||||
title="Handle 2FA"
|
||||
href="/developers/credentials/handle-2fa"
|
||||
>
|
||||
TOTP setup, pushed codes, polled endpoints, and magic links.
|
||||
</Card>
|
||||
<Card
|
||||
title="Troubleshoot logins"
|
||||
href="/developers/credentials/troubleshooting-login"
|
||||
>
|
||||
Debug 2FA and login failures.
|
||||
</Card>
|
||||
<Card
|
||||
title="SDK reference"
|
||||
href="/sdk-reference/browser-automation/agent-login"
|
||||
>
|
||||
`agent.login()`, `send_totp_code()`, and the credentials API.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Browser Sessions
|
||||
subtitle: Keep a live browser open across multiple tasks and workflows
|
||||
description: Skyvern browser sessions are live browser instances that persist cookies, local storage, and page state across runs. Use them for back-to-back tasks, human-in-the-loop flows, and real-time agents.
|
||||
slug: developers/features/browser-sessions
|
||||
icon: window-restore
|
||||
keywords:
|
||||
- browser sessions
|
||||
- persistent state
|
||||
- human-in-the-loop
|
||||
- real-time agent
|
||||
- cookies
|
||||
- local storage
|
||||
- browser profile
|
||||
---
|
||||
|
||||
A Browser Session is a live browser instance that Skyvern keeps running between runs. Cookies, local storage, open tabs, and the current page all persist, so later operations pick up exactly where the previous one stopped.
|
||||
|
||||
## What you can build
|
||||
|
||||
**Back-to-back tasks:** log in with one operation, search and extract with the next, with no re-authentication in between.
|
||||
|
||||
**Human-in-the-loop flows:** pause for approval between steps without losing browser state. The VNC stream lets you watch or take control at any point.
|
||||
|
||||
**Real-time agents:** keep a browser open for hours while the agent responds to events as they happen.
|
||||
|
||||
**Task and workflow chaining:** run tasks and workflows through the same live browser instance, mixing code-driven and UI-defined automation in a single session.
|
||||
|
||||
## Configuration
|
||||
|
||||
Sessions support timeouts from 5 minutes to 24 hours (defaulting to 60 minutes), proxy locations across any of Skyvern's [21 supported countries](/developers/going-to-production/proxy-geolocation), Chrome or Edge browser types, and built-in extensions for ad-blocking and CAPTCHA solving. Every session exposes a live VNC stream.
|
||||
|
||||
## Sessions vs. Profiles
|
||||
|
||||
Sessions are live browsers that bill while open. [Browser Profiles](/developers/optimization/browser-profiles) are saved snapshots of browser state you reuse across days or weeks. You can create a profile from a finished session to save its authenticated state for later.
|
||||
|
||||
## Learn more
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Browser sessions guide"
|
||||
href="/developers/optimization/browser-sessions"
|
||||
>
|
||||
Create sessions, run operations through them, and close cleanly.
|
||||
</Card>
|
||||
<Card
|
||||
title="Browser profiles"
|
||||
href="/developers/optimization/browser-profiles"
|
||||
>
|
||||
Save state to reuse across days or weeks.
|
||||
</Card>
|
||||
<Card
|
||||
title="Connect your local browser"
|
||||
href="/developers/self-hosted/browser"
|
||||
>
|
||||
Use your own Chrome with its existing logins and extensions.
|
||||
</Card>
|
||||
<Card
|
||||
title="SDK reference"
|
||||
href="/sdk-reference/browser-sessions/create-browser-session"
|
||||
>
|
||||
`create_browser_session`, `get_browser_session`, `close_browser_session`.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: CAPTCHA & Bot Bypass
|
||||
subtitle: How Skyvern handles CAPTCHAs and avoids triggering anti-bot systems
|
||||
description: Learn how Skyvern automatically detects and solves CAPTCHAs including reCAPTCHA, hCaptcha, and Cloudflare Turnstile, and how to reduce bot detection risk using residential proxies, browser sessions, and browser profiles.
|
||||
slug: developers/features/captcha-and-bot-bypass
|
||||
icon: shield-halved
|
||||
keywords:
|
||||
- CAPTCHA
|
||||
- reCAPTCHA
|
||||
- hCaptcha
|
||||
- Cloudflare Turnstile
|
||||
- bot detection
|
||||
- fingerprinting
|
||||
- residential proxy
|
||||
- stealth
|
||||
- anti-bot
|
||||
---
|
||||
|
||||
Skyvern detects CAPTCHAs using its vision model and solves them automatically. This works for reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, FunCaptcha/ArkoseLabs, MTCaptcha, and standard text/number image CAPTCHAs.
|
||||
|
||||
That said, CAPTCHA solving is not guaranteed. Solvers can fail on novel challenges or rate-limited IPs. The rest of this page covers what Skyvern does automatically and what you can do to improve your success rate.
|
||||
|
||||
## Built-in bot detection avoidance
|
||||
|
||||
Every run gets these protections automatically, with no configuration needed:
|
||||
|
||||
- The `AutomationControlled` Blink feature flag is disabled so the browser isn't marked as automated.
|
||||
- `navigator.webdriver` is hidden by suppressing the `enable-automation` flag, which defeats the most common JavaScript detection scripts.
|
||||
- Viewport and user agent are set to match real consumer browsers.
|
||||
- Locale and timezone auto-match the proxy location, so you never end up with a mismatched fingerprint (an English locale on a Japanese IP, for example).
|
||||
|
||||
## Reducing detection risk
|
||||
|
||||
Beyond fingerprinting, how you structure your automation affects whether you get flagged.
|
||||
|
||||
**Use residential proxies for sensitive sites.** Datacenter IPs are the single most common bot signal. Residential proxies route through real ISP addresses. Set `proxy_location="RESIDENTIAL"` or use `RESIDENTIAL_ISP` for a static IP that persists across the session. See [Proxy & Geolocation](/developers/going-to-production/proxy-geolocation).
|
||||
|
||||
**Reuse browser sessions for multi-step flows.** Creating a fresh browser for every step is suspicious. A persistent session maintains cookies, cache, and history between operations. See [Browser Sessions](/developers/optimization/browser-sessions).
|
||||
|
||||
**Use browser profiles for repeat visits.** Profiles save browser state from a previous session. The site sees a known browser with familiar cookies instead of a blank slate. See [Browser Profiles](/developers/optimization/browser-profiles).
|
||||
|
||||
**Add wait blocks between rapid actions.** Instant back-to-back actions can trigger behavioral detection. A short pause between steps looks more human.
|
||||
|
||||
## If you get blocked
|
||||
|
||||
Increase `max_steps` first, because some bot challenges (especially Cloudflare) loop through multiple verification pages and the solver needs more attempts. If that doesn't help, switch to a `RESIDENTIAL_ISP` proxy for a static IP that services trust more. Try loading a browser profile that previously passed the challenge on that domain. You can also load Chrome extensions for additional stealth by setting `EXTENSIONS` and `EXTENSIONS_BASE_PATH` in your environment.
|
||||
|
||||
## Manual fallback
|
||||
|
||||
If automatic solving fails and you need a human in the loop, you can manually solve any CAPTCHA without cancelling the run. In the Cloud UI, go to **Runs**, click your run, and click the **Take Control** button over the browser stream. Release control when you're done and the agent resumes where you left off.
|
||||
|
||||
<img src="/images/take-control.png" />
|
||||
|
||||
## Self-hosted deployments
|
||||
|
||||
Automatic CAPTCHA solving is not available for self-hosted deployments. When a CAPTCHA is detected, the agent pauses for 30 seconds to allow manual intervention. Solve it in the browser window yourself, then the agent continues automatically.
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Proxy & Geolocation"
|
||||
href="/developers/going-to-production/proxy-geolocation"
|
||||
>
|
||||
Route traffic through residential proxies in 21 countries.
|
||||
</Card>
|
||||
<Card
|
||||
title="Handle 2FA"
|
||||
href="/developers/credentials/handle-2fa"
|
||||
>
|
||||
Configure TOTP, email, and SMS verification codes.
|
||||
</Card>
|
||||
<Card
|
||||
title="Browser Sessions"
|
||||
href="/developers/optimization/browser-sessions"
|
||||
>
|
||||
Persist browser state across multiple runs.
|
||||
</Card>
|
||||
<Card
|
||||
title="Error Handling"
|
||||
href="/developers/going-to-production/error-handling"
|
||||
>
|
||||
Map CAPTCHA and bot failures to custom error codes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Code Caching
|
||||
subtitle: Convert successful runs into cached code for faster, deterministic replays
|
||||
description: Skyvern records the actions an AI run takes and generates executable code from them. Subsequent runs execute the cached code directly, skipping LLM inference and screenshot analysis. Faster, cheaper, deterministic.
|
||||
slug: developers/features/code-caching
|
||||
icon: bolt
|
||||
keywords:
|
||||
- code caching
|
||||
- code generation
|
||||
- run_with
|
||||
- Skyvern 2.0 with Code
|
||||
- deterministic runs
|
||||
- script generation
|
||||
- cost optimization
|
||||
- progressive caching
|
||||
---
|
||||
|
||||
When Skyvern's agent completes a task or workflow, it records the actions it took and generates reusable code from them. Later runs can execute that cached code directly, skipping LLM inference and screenshot analysis entirely. This makes cached runs faster, cheaper, and deterministic. If the cached code fails because a page changed, Skyvern falls back to the agent automatically and regenerates the cache.
|
||||
|
||||
## How it works
|
||||
|
||||
The first run uses the agent as normal. Set `engine="skyvern-2.0"` when creating the task or workflow, and Skyvern records the actions as generated code while the agent executes.
|
||||
|
||||
On subsequent runs, pass `run_with="code"` to execute the cached code directly. No screenshots, no LLM reasoning, just the recorded action sequence replaying against the page.
|
||||
|
||||
If the cached code hits something unexpected (a layout change, a new field, a missing element), Skyvern re-runs with the full agent and regenerates the cache. You don't need to handle this yourself.
|
||||
|
||||
<Note>
|
||||
The SDK default engine is `skyvern-1.0`. To use code caching, explicitly set `engine="skyvern-2.0"`. In the Cloud UI, `skyvern-2.0` is the default.
|
||||
</Note>
|
||||
|
||||
## What gets cached
|
||||
|
||||
**Tasks** cache the full action sequence the agent took: clicks, form fills, extractions, and navigation.
|
||||
|
||||
**Workflows** cache per block. Each block that successfully executes gets its own cached script, so a partially-cached workflow still saves time on the blocks that have been seen before.
|
||||
|
||||
**Progressive caching** handles workflows with conditionals. Run 1 covers branch A, run 2 covers branch B, and so on. Previous caches are preserved, so coverage builds up over time.
|
||||
|
||||
**Not cached:** conditional evaluation blocks, wait blocks, and code blocks always run live because their behavior depends on runtime state.
|
||||
|
||||
<Tip>
|
||||
Pair cached code with [scheduled workflows](/cloud/building-workflows/scheduling) for cheap, reliable recurring runs. The first scheduled run builds the cache, and every subsequent run executes from it.
|
||||
</Tip>
|
||||
|
||||
## Learn more
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Cost control"
|
||||
href="/developers/optimization/cost-control"
|
||||
>
|
||||
Use `run_with: code` plus `max_steps` and engine tiers to manage costs.
|
||||
</Card>
|
||||
<Card
|
||||
title="Scheduling workflows"
|
||||
href="/cloud/building-workflows/scheduling"
|
||||
>
|
||||
Run cached workflows on a cron schedule.
|
||||
</Card>
|
||||
<Card
|
||||
title="Reliability tips"
|
||||
href="/developers/going-to-production/reliability-tips"
|
||||
>
|
||||
Keep cached runs stable as target sites evolve.
|
||||
</Card>
|
||||
<Card
|
||||
title="Run from code"
|
||||
href="/cloud/building-workflows/run-from-code"
|
||||
>
|
||||
Trigger and monitor cached workflows from your own code.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Proxy & GEO Targeting
|
||||
subtitle: Route browser traffic through residential IPs in 21 countries
|
||||
description: Skyvern routes browser traffic through residential proxies in 21 countries, with city- and state-level targeting in the US. Use it to access region-locked content, test geo-specific experiences, and reduce bot detection risk.
|
||||
slug: developers/features/proxy-and-geo-targeting
|
||||
icon: globe
|
||||
keywords:
|
||||
- proxy
|
||||
- geolocation
|
||||
- residential proxy
|
||||
- RESIDENTIAL
|
||||
- RESIDENTIAL_ISP
|
||||
- GeoTarget
|
||||
- geo-targeting
|
||||
- country
|
||||
- city
|
||||
---
|
||||
|
||||
Skyvern routes browser traffic through residential proxies so every run looks like it's coming from a real consumer ISP in the country you choose. Locale and timezone auto-match the proxy region, so you never end up with a mismatched fingerprint that gives the automation away.
|
||||
|
||||
## Coverage
|
||||
|
||||
21 countries of residential coverage spanning the Americas (US, CA, MX, AR, BR), Europe (GB, IE, NL, DE, FR, ES, IT, TR), Asia (IN, PH, KR, JP, SA), Africa (ZA), and Oceania (AU, NZ).
|
||||
|
||||
For services that require a stable IP across a session, `RESIDENTIAL_ISP` provides a static ISP address instead of a rotating one. In the United States, you can target down to city and state level using `GeoTarget`, for example `{"country": "US", "subdivision": "CA", "city": "San Francisco"}`.
|
||||
|
||||
## How it's applied
|
||||
|
||||
**Per task:** pass `proxy_location` in the run request. **Per workflow:** set a default on the workflow and override on any individual run. **Per session:** lock a proxy to a [browser session](/developers/optimization/browser-sessions) so every operation in that session shares the same IP.
|
||||
|
||||
## When to use it
|
||||
|
||||
Region-locked pricing, inventory, or UX becomes visible when you route through the right country. Regulatory filings that require a local IP can be submitted from inside the target jurisdiction. Residential IPs also help with bot detection since they look like real consumer traffic rather than a datacenter. And `RESIDENTIAL_ISP` keeps the same IP for a full session, which matters for services that track IP changes mid-flow.
|
||||
|
||||
## Learn more
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Proxy & geolocation guide"
|
||||
href="/developers/going-to-production/proxy-geolocation"
|
||||
>
|
||||
Full country list, `proxy_location` values, and `GeoTarget` examples.
|
||||
</Card>
|
||||
<Card
|
||||
title="CAPTCHA & bot bypass"
|
||||
href="/developers/features/captcha-and-bot-bypass"
|
||||
>
|
||||
Pair residential proxies with stealth for sensitive sites.
|
||||
</Card>
|
||||
<Card
|
||||
title="Browser sessions"
|
||||
href="/developers/optimization/browser-sessions"
|
||||
>
|
||||
Lock a proxy location across multiple operations in one session.
|
||||
</Card>
|
||||
<Card
|
||||
title="Self-hosted proxy"
|
||||
href="/developers/self-hosted/proxy"
|
||||
>
|
||||
Bring your own proxy on self-hosted deployments.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: AI Agents Quickstart
|
||||
subtitle: Give your AI coding assistant full browser automation in one command
|
||||
description: Give your AI coding assistant full browser control capabilities in one prommpt
|
||||
slug: developers/getting-started/ai-agents-quickstart
|
||||
keywords:
|
||||
- MCP
|
||||
- Claude Desktop
|
||||
- Cursor
|
||||
- Windsurf
|
||||
- VS Code
|
||||
- AI assistant
|
||||
- Model Context Protocol
|
||||
- pip install
|
||||
- npm install
|
||||
---
|
||||
|
||||
import AIAgentsQuickstartContent from "/snippets/ai-agents-quickstart-content.mdx";
|
||||
|
||||
<AIAgentsQuickstartContent />
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Core Concepts
|
||||
subtitle: The building blocks of Skyvern automations
|
||||
description: Learn about tasks, workflows, browser sessions, credentials, and other building blocks that make up Skyvern automations.
|
||||
slug: developers/getting-started/core-concepts
|
||||
keywords:
|
||||
- task
|
||||
- workflow
|
||||
- browser session
|
||||
- browser profile
|
||||
- credential
|
||||
- block
|
||||
- parameter
|
||||
- schedule
|
||||
- navigation block
|
||||
- action block
|
||||
- extract block
|
||||
- loop block
|
||||
- text prompt block
|
||||
---
|
||||
|
||||
import CoreConceptsContent from "/snippets/core-concepts-content.mdx";
|
||||
|
||||
<CoreConceptsContent />
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: What is Skyvern?
|
||||
subtitle: AI-powered browser automation for any website
|
||||
description: Skyvern automates browser-based workflows using LLMs and computer vision. It navigates websites it has never seen before, filling forms, extracting data, and completing multi-step tasks via a simple API.
|
||||
slug: developers/getting-started/introduction
|
||||
keywords:
|
||||
- browser automation
|
||||
- AI agent
|
||||
- computer vision
|
||||
- LLM
|
||||
- natural language
|
||||
- visual reasoning
|
||||
- web scraping
|
||||
- form filling
|
||||
- Playwright
|
||||
---
|
||||
|
||||
import IntroductionContent from "/snippets/introduction-content.mdx";
|
||||
|
||||
<IntroductionContent />
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: MCP Server
|
||||
subtitle: Connect AI assistants to browser automation via Model Context Protocol
|
||||
description: Install and configure Skyvern's MCP server so Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Hermes, OpenClaw, and other AI tools can run browser automations against Skyvern Cloud or a self-hosted instance over OAuth, API key, or local stdio.
|
||||
slug: developers/getting-started/mcp
|
||||
keywords:
|
||||
- MCP
|
||||
- Model Context Protocol
|
||||
- OAuth
|
||||
- Claude Desktop
|
||||
- Claude Code
|
||||
- Cursor
|
||||
- Windsurf
|
||||
- Codex
|
||||
- Hermes
|
||||
- OpenClaw
|
||||
- MCPorter
|
||||
- AI assistant
|
||||
- tools
|
||||
- stdio
|
||||
- streamable-http
|
||||
- self-hosted
|
||||
---
|
||||
|
||||
import McpContent from "/snippets/mcp-content.mdx";
|
||||
|
||||
<McpContent />
|
||||
@@ -0,0 +1,355 @@
|
||||
---
|
||||
title: Quickstart
|
||||
subtitle: Run your first browser automation in 5 minutes
|
||||
description: Launch a cloud browser, go to a webpage, and extract structured data with Python, TypeScript, or cURL in under 5 minutes.
|
||||
slug: developers/getting-started/quickstart
|
||||
keywords:
|
||||
- quickstart
|
||||
- launch_cloud_browser
|
||||
- get_working_page
|
||||
- page.extract
|
||||
- page.agent.run_task
|
||||
- cURL
|
||||
- Python
|
||||
- Typescript
|
||||
- pip install
|
||||
- npm install
|
||||
- installation
|
||||
---
|
||||
|
||||
Run your first browser automation in 5 minutes. By the end of this guide, you'll launch a cloud browser, navigate to Hacker News, and extract the top post title using Skyvern SDK's Page, Agent and Browser methods.
|
||||
|
||||
<Note>
|
||||
Prefer a visual interface? Try the [Cloud UI](/cloud/getting-started/overview) instead. No code required.
|
||||
</Note>
|
||||
|
||||
## Step 1: Get your API key
|
||||
|
||||
<img src="/images/get-api-key.png" alt="Get Skyvern API key" />
|
||||
|
||||
Sign up at [app.skyvern.com](https://app.skyvern.com) and go to [Settings](https://app.skyvern.com/settings) to copy your API key.
|
||||
|
||||
## Step 2: Install the SDK
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
pip install skyvern
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npm install @skyvern/client
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
`pip install skyvern` is the lightweight Python SDK for Skyvern Cloud and remote API usage. If you are using embedded local mode with `Skyvern.local()` or `launch_local_browser()`, install the local extra: `pip install "skyvern[local]"`. For a local Skyvern server, self-hosted instance, or local stdio MCP, install the server extra instead: `pip install "skyvern[server]"`. For full local setup with migrations and the web UI, use Docker Compose or a source checkout.
|
||||
</Info>
|
||||
|
||||
<Accordion title="Troubleshooting: Python version errors">
|
||||
The Skyvern SDK requires Python 3.11, 3.12, or 3.13. If you encounter version errors, try using pipx:
|
||||
|
||||
```bash
|
||||
pipx install skyvern
|
||||
```
|
||||
|
||||
pipx installs Python packages in isolated environments while making them globally available.
|
||||
</Accordion>
|
||||
|
||||
## Step 3: Launch a browser and extract data
|
||||
|
||||
When you call `launch_cloud_browser()`, Skyvern spins up a Chromium instance in the cloud. Your code drives that browser via a Playwright `Page` that also has AI methods (`act`, `extract`, `validate`, `prompt`) layered on top. You can watch the browser live at any time.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
skyvern = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
# 1. Launch a cloud browser and get a page
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
print(f"Watch live: https://app.skyvern.com/browser-session/{browser.browser_session_id}")
|
||||
|
||||
try:
|
||||
# 2. Navigate
|
||||
await page.goto("https://news.ycombinator.com")
|
||||
|
||||
# 3. Extract data with an AI prompt
|
||||
result = await page.extract("Get the title of the #1 post")
|
||||
print(f"Extracted: {result}")
|
||||
finally:
|
||||
# 4. Always close the browser to free cloud resources
|
||||
await browser.close()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const skyvern = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY });
|
||||
|
||||
// 1. Launch a cloud browser and get a page
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
console.log(`Watch live: https://app.skyvern.com/browser-session/${browser.browserSessionId}`);
|
||||
|
||||
try {
|
||||
// 2. Navigate
|
||||
await page.goto("https://news.ycombinator.com");
|
||||
|
||||
// 3. Extract data with an AI prompt
|
||||
const result = await page.extract("Get the title of the #1 post");
|
||||
console.log("Extracted:", result);
|
||||
} finally {
|
||||
// 4. Always close the browser to free cloud resources
|
||||
await browser.close();
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# The SDK's browser/page pattern is a client-side abstraction over several
|
||||
# REST calls. For a single curl example, use the task API, which handles
|
||||
# browser + navigation + extraction as one request:
|
||||
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Go to news.ycombinator.com and get the title of the #1 post",
|
||||
"url": "https://news.ycombinator.com"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
**Why `page.extract` is enough here.** For a one-shot read on a single page, `page.extract(prompt, schema=...)` returns the extracted data directly (a `dict` in Python, `object` in TS). For multi-step goals like *"log in, navigate to billing, download the invoice"*, use `page.agent.run_task(prompt)` instead; it runs a full AI task loop on the page and returns a [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse). See [Build a Browser Automation](/developers/browser-automations/overview) for the full walkthrough.
|
||||
</Info>
|
||||
|
||||
## Step 4: Understand the output
|
||||
|
||||
`page.extract` returns the extracted data as a dict. For the Hacker News example you'll see something like:
|
||||
|
||||
```text
|
||||
Watch live: https://app.skyvern.com/browser-session/pbs_519891155782767800
|
||||
Extracted: {'top_post_title': 'Linux kernel framework for PCIe device emulation, in userspace'}
|
||||
```
|
||||
|
||||
- **`Watch live: ...`** is printed before any AI calls. Open it in another tab to watch the browser navigate and extract in real time.
|
||||
- **`Extracted: {...}`** appears after `page.extract` returns. The key names come from the AI (unless you pass a `schema`, in which case they match your schema). For typed, predictable output, see [Extract Structured Data](/developers/browser-automations/extract-structured-data).
|
||||
|
||||
### If you used the cURL path
|
||||
|
||||
The task API is asynchronous. The POST returns a `run_id`; poll for the final result:
|
||||
|
||||
```bash
|
||||
RUN_ID="tsk_..." # from the POST response above
|
||||
|
||||
while true; do
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo "$RESPONSE" | jq -r '.status')
|
||||
echo "Status: $STATUS"
|
||||
|
||||
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
|
||||
echo "$RESPONSE" | jq '.output'
|
||||
break
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
|
||||
**Run states:**
|
||||
- `created`, `queued`: Waiting for an available browser
|
||||
- `running`: AI is navigating and executing
|
||||
- `completed`: Task finished successfully
|
||||
- `failed` / `terminated` / `timed_out` / `canceled`: Non-success terminal states
|
||||
|
||||
## Step 5: Watch the recording
|
||||
|
||||
Every run is recorded. Two ways to access it:
|
||||
|
||||
### Live
|
||||
|
||||
While the script runs, the `Watch live: ...` URL printed in Step 3 streams the browser in real time.
|
||||
|
||||
### After the run
|
||||
|
||||
Open [Runs](https://app.skyvern.com/runs) and click on your run to see the Recording tab, step-by-step actions with screenshots, and AI reasoning for each decision.
|
||||
|
||||
<img src="/images/view-recording.png" alt="Recording tab in Skyvern Cloud" />
|
||||
|
||||
This is invaluable for debugging and understanding how Skyvern interprets your prompts.
|
||||
|
||||
---
|
||||
|
||||
## Run with a local server
|
||||
|
||||
You can run Skyvern with a browser on your own machine. This is useful for development, debugging, or automating internal tools on your local network.
|
||||
|
||||
**Prerequisites:**
|
||||
- Skyvern server extra installed (`pip install "skyvern[server]"`)
|
||||
- Source checkout or Docker Compose for guided quickstart and database migrations
|
||||
- PostgreSQL database (local install or Docker)
|
||||
- An LLM API key (OpenAI, Anthropic, Azure OpenAI, Gemini, Ollama, or any OpenAI-compatible provider)
|
||||
|
||||
<Note>
|
||||
Docker is optional. If you have PostgreSQL installed locally, Skyvern will detect and use it automatically. Use `skyvern init --no-postgres` to skip database setup entirely if you're managing PostgreSQL separately. The PyPI wheel installs the local-server dependencies, but guided quickstart currently needs repository migration files from a source checkout.
|
||||
</Note>
|
||||
|
||||
### Set up local Skyvern
|
||||
|
||||
```bash
|
||||
# Run this from your app or repo root if you want Claude Code + /qa set up in-place
|
||||
skyvern quickstart
|
||||
|
||||
# Or use setup-only mode if you do not want to start services yet
|
||||
skyvern init
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img src="/images/skyvern-init.gif" alt="Skyvern init interactive setup wizard" />
|
||||
</p>
|
||||
|
||||
|
||||
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. Optionally configure local MCP for Claude Code, Claude Desktop, Cursor, or Windsurf
|
||||
6. Download the Chromium browser
|
||||
|
||||
If you choose **Claude Code** during the MCP step and you run the wizard inside a project or repo, Skyvern will:
|
||||
|
||||
- write a project-local `.mcp.json`
|
||||
- pin the MCP command to the active Python interpreter (`/path/to/python -m skyvern run mcp`)
|
||||
- install bundled Claude Code skills into `.claude/skills/`, including `/qa`
|
||||
- keep the whole path local, so Claude Code can test `localhost` directly without Skyvern Cloud or browser tunneling
|
||||
|
||||
This will generate a .env file that stores your local configuration, LLM api keys and your local `BASE_URL` and `SKYVERN_API_KEY`:
|
||||
```.env
|
||||
ENV='local'
|
||||
ENABLE_OPENAI='true'
|
||||
OPENAI_API_KEY='<API_KEY>'
|
||||
...
|
||||
LLM_KEY='OPENAI_GPT5_5'
|
||||
SECONDARY_LLM_KEY=''
|
||||
BROWSER_TYPE='chromium-headful'
|
||||
MAX_SCRAPING_RETRIES='0'
|
||||
VIDEO_PATH='./videos'
|
||||
BROWSER_ACTION_TIMEOUT_MS='5000'
|
||||
MAX_STEPS_PER_RUN='50'
|
||||
LOG_LEVEL='INFO'
|
||||
LITELLM_LOG='CRITICAL'
|
||||
DATABASE_STRING='postgresql+psycopg://skyvern@localhost/skyvern'
|
||||
PORT='8000'
|
||||
...
|
||||
SKYVERN_BASE_URL='http://localhost:8000'
|
||||
SKYVERN_API_KEY='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....hSo3YA'
|
||||
```
|
||||
|
||||
### Start the local server
|
||||
|
||||
If you used `skyvern quickstart` and chose to start services, Skyvern is already running. If you used `skyvern init`, start the server with:
|
||||
|
||||
```bash
|
||||
skyvern run server
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img src="/images/skyvern-run-server.gif" alt="Skyvern local server logs" />
|
||||
</p>
|
||||
|
||||
### Run locally
|
||||
|
||||
The only difference from cloud is the `base_url` parameter pointing to your local server. The Page/Agent/Browser API is identical, so the same code works in both environments. Develop locally, deploy to cloud without changes.
|
||||
|
||||
```python
|
||||
import os
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
skyvern = Skyvern(
|
||||
base_url="http://localhost:8000",
|
||||
api_key=os.getenv("SKYVERN_API_KEY"),
|
||||
)
|
||||
|
||||
browser = await skyvern.launch_local_browser()
|
||||
page = await browser.get_working_page()
|
||||
|
||||
try:
|
||||
await page.goto("https://news.ycombinator.com")
|
||||
result = await page.extract("Get the title of the #1 post")
|
||||
print(f"Extracted: {result}")
|
||||
finally:
|
||||
await browser.close()
|
||||
|
||||
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.
|
||||
|
||||
If you also selected Claude Code during setup, start your local frontend dev server and run `/qa http://localhost:3000` in Claude Code to validate the app against your local environment.
|
||||
|
||||
<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
|
||||
<source src="https://github.com/naman06dev/skyvern-docs/raw/8706c85d746e2a6870d81b6a95eaa511ad66dbf8/fern/images/skyvern-agent-local.mp4" type="video/mp4" />
|
||||
</video>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Build a Browser Automation"
|
||||
icon="browser"
|
||||
href="/developers/browser-automations/overview"
|
||||
>
|
||||
The full Page/Agent/Browser walkthrough: AI actions, Playwright selectors, and agent tasks
|
||||
</Card>
|
||||
<Card
|
||||
title="Actions Reference"
|
||||
icon="list"
|
||||
href="/developers/browser-automations/actions-reference"
|
||||
>
|
||||
Every page action and agent method with parameters and return types
|
||||
</Card>
|
||||
<Card
|
||||
title="Extract Structured Data"
|
||||
icon="database"
|
||||
href="/developers/browser-automations/extract-structured-data"
|
||||
>
|
||||
Define a schema to get typed JSON output from your automations
|
||||
</Card>
|
||||
<Card
|
||||
title="Handle Logins"
|
||||
icon="key"
|
||||
href="/sdk-reference/credentials/create-credential"
|
||||
>
|
||||
Store credentials securely for sites that require authentication
|
||||
</Card>
|
||||
<Card
|
||||
title="Build Workflows"
|
||||
icon="diagram-project"
|
||||
href="/cloud/building-workflows/build-a-workflow"
|
||||
>
|
||||
Chain multiple steps together for complex automations
|
||||
</Card>
|
||||
<Card
|
||||
title="Use Webhooks"
|
||||
icon="webhook"
|
||||
href="/developers/going-to-production/webhooks"
|
||||
>
|
||||
Get notified when tasks complete instead of polling
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,705 @@
|
||||
---
|
||||
title: Error Handling
|
||||
subtitle: Build systems that detect, classify, and recover from failures
|
||||
description: Detect, classify, and recover from task and workflow failures using run status, failure_reason, custom error_code_mapping, and validation blocks. Build programmatic error handling with retry logic and branching.
|
||||
slug: developers/going-to-production/error-handling
|
||||
keywords:
|
||||
- failure_reason
|
||||
- run status
|
||||
- error_code_mapping
|
||||
- validation block
|
||||
- retry logic
|
||||
- branching
|
||||
- failed
|
||||
- terminated
|
||||
- timed_out
|
||||
---
|
||||
|
||||
Skyvern lets you make your workflows and tasks handle errors gracefully instead of failing silently.
|
||||
|
||||
Every run returns a `status`. When it's not `completed`, you need to know what went wrong and respond programmatically. The flow is:
|
||||
|
||||
1. **Check `status`** to detect failure states
|
||||
2. **Read `failure_reason`** to get the raw error description
|
||||
3. **Set up `error_code_mapping`** to map failures to your own error codes
|
||||
4. **Respond in code** to branch your logic based on the error code
|
||||
|
||||
This page covers each step with exact field locations and full code examples.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check `status`
|
||||
|
||||
Every run transitions through these states:
|
||||
|
||||
| Status | What it means |
|
||||
|--------|---------------|
|
||||
| `created` | Run initialized, not yet queued |
|
||||
| `queued` | Waiting for an available browser |
|
||||
| `running` | AI is navigating and executing |
|
||||
| `completed` | Success. Check `output` for results |
|
||||
| `failed` | System error (browser crash, network failure, exception) |
|
||||
| `terminated` | AI determined the goal is unachievable (login blocked, page unavailable) |
|
||||
| `timed_out` | Exceeded `max_steps` or time limit |
|
||||
| `canceled` | Manually stopped |
|
||||
|
||||
**Terminal states:** `completed`, `failed`, `terminated`, `timed_out`, `canceled`
|
||||
|
||||
You can detect failures in two ways:
|
||||
|
||||
1. by polling `get_run`
|
||||
2. by checking the webhook payload
|
||||
|
||||
Both contain the same `status` field.
|
||||
|
||||
<CodeGroup>
|
||||
```json Polling Response
|
||||
{
|
||||
"run_id": "tsk_v2_486305187432193504",
|
||||
"status": "failed", // <-- Check this field
|
||||
"output": null,
|
||||
"failure_reason": "Login failed: Invalid credentials",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
```json Webhook Payload
|
||||
{
|
||||
"run_id": "tsk_v2_486306851394503256",
|
||||
"status": "completed", // <-- Check this field
|
||||
"output": {
|
||||
"top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
|
||||
},
|
||||
"failure_reason": null,
|
||||
"errors": [],
|
||||
"webhook_callback_url": "https://your-server.com/webhook",
|
||||
"created_at": "2026-01-20T11:58:57.414123",
|
||||
"finished_at": "2026-01-20T12:00:31.512692",
|
||||
...
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The `status` field is at the top level of both responses.
|
||||
|
||||
### For tasks
|
||||
|
||||
Poll `get_run` until the status is terminal:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run_id = result.run_id
|
||||
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
|
||||
await asyncio.sleep(5)
|
||||
|
||||
if run.status == "completed":
|
||||
process_output(run.output)
|
||||
else:
|
||||
handle_failure(run)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const runId = result.run_id;
|
||||
|
||||
while (true) {
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
|
||||
break;
|
||||
}
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 5000));
|
||||
}
|
||||
|
||||
if (run.status === "completed") {
|
||||
processOutput(run.output);
|
||||
} else {
|
||||
handleFailure(run);
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Poll until terminal state
|
||||
while true; do
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo $RESPONSE | jq -r '.status')
|
||||
|
||||
if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "failed" ]] || \
|
||||
[[ "$STATUS" == "terminated" ]] || [[ "$STATUS" == "timed_out" ]] || \
|
||||
[[ "$STATUS" == "canceled" ]]; then
|
||||
echo $RESPONSE | jq
|
||||
break
|
||||
fi
|
||||
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### For workflows
|
||||
|
||||
Same polling pattern works for workflow runs:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run_id = result.run_id
|
||||
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
|
||||
await asyncio.sleep(5)
|
||||
|
||||
if run.status == "completed":
|
||||
process_output(run.output)
|
||||
else:
|
||||
handle_failure(run)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const runId = result.run_id;
|
||||
|
||||
while (true) {
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
|
||||
break;
|
||||
}
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 5000));
|
||||
}
|
||||
|
||||
if (run.status === "completed") {
|
||||
processOutput(run.output);
|
||||
} else {
|
||||
handleFailure(run);
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Poll workflow run until terminal state
|
||||
while true; do
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$WORKFLOW_RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo $RESPONSE | jq -r '.status')
|
||||
|
||||
if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "failed" ]] || \
|
||||
[[ "$STATUS" == "terminated" ]] || [[ "$STATUS" == "timed_out" ]] || \
|
||||
[[ "$STATUS" == "canceled" ]]; then
|
||||
echo $RESPONSE | jq
|
||||
break
|
||||
fi
|
||||
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**`failed` vs `terminated`:** A `failed` run hit infrastructure problems, so retry might work. A `terminated` run means the AI recognized the goal is unachievable with current conditions. Retrying without changes (new credentials, different URL) will produce the same result.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read `failure_reason`
|
||||
|
||||
When a run fails or terminates, the `failure_reason` field contains a description of what went wrong. This is a free-text string, useful for logging but hard to branch on programmatically.
|
||||
|
||||
The field is available in both the polling response and webhook payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "tsk_v2_486305187432193504",
|
||||
"status": "terminated",
|
||||
"output": null,
|
||||
"failure_reason": "Login failed: The page displayed 'Invalid username or password' after submitting credentials", // <-- Raw error text
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### For tasks
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status in ["failed", "terminated"]:
|
||||
print(f"Run failed: {run.failure_reason}")
|
||||
|
||||
# Fragile: parsing free text
|
||||
if "login" in run.failure_reason.lower():
|
||||
refresh_credentials()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (["failed", "terminated"].includes(run.status)) {
|
||||
console.log(`Run failed: ${run.failure_reason}`);
|
||||
|
||||
// Fragile: parsing free text
|
||||
if (run.failure_reason?.toLowerCase().includes("login")) {
|
||||
refreshCredentials();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo $RESPONSE | jq -r '.status')
|
||||
FAILURE_REASON=$(echo $RESPONSE | jq -r '.failure_reason')
|
||||
|
||||
if [[ "$STATUS" == "failed" ]] || [[ "$STATUS" == "terminated" ]]; then
|
||||
echo "Run failed: $FAILURE_REASON"
|
||||
|
||||
# Fragile: parsing free text
|
||||
if echo "$FAILURE_REASON" | grep -qi "login"; then
|
||||
# refresh_credentials
|
||||
echo "Login error detected"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### For workflows
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run = await client.get_run(workflow_run_id)
|
||||
|
||||
if run.status in ["failed", "terminated"]:
|
||||
print(f"Workflow failed: {run.failure_reason}")
|
||||
|
||||
# Fragile: parsing free text
|
||||
if "login" in run.failure_reason.lower():
|
||||
refresh_credentials()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const run = await client.getRun(workflowRunId);
|
||||
|
||||
if (["failed", "terminated"].includes(run.status)) {
|
||||
console.log(`Workflow failed: ${run.failure_reason}`);
|
||||
|
||||
// Fragile: parsing free text
|
||||
if (run.failure_reason?.toLowerCase().includes("login")) {
|
||||
refreshCredentials();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$WORKFLOW_RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo $RESPONSE | jq -r '.status')
|
||||
FAILURE_REASON=$(echo $RESPONSE | jq -r '.failure_reason')
|
||||
|
||||
if [[ "$STATUS" == "failed" ]] || [[ "$STATUS" == "terminated" ]]; then
|
||||
echo "Workflow failed: $FAILURE_REASON"
|
||||
|
||||
# Fragile: parsing free text
|
||||
if echo "$FAILURE_REASON" | grep -qi "login"; then
|
||||
# refresh_credentials
|
||||
echo "Login error detected"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Use `error_code_mapping`
|
||||
|
||||
`failure_reason` contains an AI-generated description of what went wrong. Define custom error codes to get consistent, actionable error messages.
|
||||
|
||||
When the run fails, Skyvern evaluates your natural language error descriptions against the page state and returns the matching code.
|
||||
|
||||
**How it works:** The `error_code_mapping` values are LLM-evaluated descriptions, so you don't need exact string matches. For example, `"The login credentials are incorrect"` will match pages showing "Invalid password", "Wrong username", "Authentication failed", etc.
|
||||
|
||||
### In tasks
|
||||
|
||||
Pass `error_code_mapping` as a parameter to `run_task`:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Log in and download the invoice for January 2024",
|
||||
url="https://vendor-portal.example.com",
|
||||
error_code_mapping={
|
||||
"login_failed": "The login credentials are incorrect, account is locked, or MFA is required",
|
||||
"invoice_not_found": "No invoice exists for the requested date range",
|
||||
"maintenance": "The website is down for maintenance or unavailable",
|
||||
"access_denied": "User does not have permission to view invoices"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Log in and download the invoice for January 2024",
|
||||
url: "https://vendor-portal.example.com",
|
||||
error_code_mapping: {
|
||||
login_failed: "The login credentials are incorrect, account is locked, or MFA is required",
|
||||
invoice_not_found: "No invoice exists for the requested date range",
|
||||
maintenance: "The website is down for maintenance or unavailable",
|
||||
access_denied: "User does not have permission to view invoices",
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Log in and download the invoice for January 2024",
|
||||
"url": "https://vendor-portal.example.com",
|
||||
"error_code_mapping": {
|
||||
"login_failed": "The login credentials are incorrect, account is locked, or MFA is required",
|
||||
"invoice_not_found": "No invoice exists for the requested date range",
|
||||
"maintenance": "The website is down for maintenance or unavailable",
|
||||
"access_denied": "User does not have permission to view invoices"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### In workflows
|
||||
|
||||
Add `error_code_mapping` to individual blocks (navigation, task, validation):
|
||||
|
||||
<Note>
|
||||
The JSON examples below include comments (`//`) for clarity. Remove comments before using in actual workflow definitions; JSON does not support comments.
|
||||
</Note>
|
||||
|
||||
<CodeGroup>
|
||||
```json JSON
|
||||
{
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "login_step",
|
||||
"url": "https://vendor-portal.example.com/login",
|
||||
"navigation_goal": "Log in using the stored credentials",
|
||||
"error_code_mapping": {
|
||||
"login_failed": "Login credentials are incorrect or account is locked",
|
||||
"mfa_required": "Two-factor authentication is being requested",
|
||||
"captcha_blocked": "CAPTCHA is displayed and cannot be bypassed"
|
||||
}
|
||||
},
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "download_invoice",
|
||||
"navigation_goal": "Download the invoice for {{invoice_date}}",
|
||||
"error_code_mapping": {
|
||||
"invoice_not_found": "No invoice found for the specified date",
|
||||
"download_failed": "Invoice exists but download button is broken or missing"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml YAML
|
||||
- block_type: navigation
|
||||
label: login_step
|
||||
url: "https://vendor-portal.example.com/login"
|
||||
navigation_goal: "Log in using the stored credentials"
|
||||
error_code_mapping:
|
||||
login_failed: "Login credentials are incorrect or account is locked"
|
||||
mfa_required: "Two-factor authentication is being requested"
|
||||
captcha_blocked: "CAPTCHA is displayed and cannot be bypassed"
|
||||
|
||||
- block_type: navigation
|
||||
label: download_invoice
|
||||
navigation_goal: "Download the invoice for {{invoice_date}}"
|
||||
error_code_mapping:
|
||||
invoice_not_found: "No invoice found for the specified date"
|
||||
download_failed: "Invoice exists but download button is broken or missing"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Where the error code appears
|
||||
|
||||
When a mapped error occurs, your code appears in `output.error`. This field is available in both polling responses and webhook payloads:
|
||||
|
||||
<CodeGroup>
|
||||
```json Polling Response
|
||||
{
|
||||
"run_id": "tsk_v2_486305187432193504",
|
||||
"status": "terminated",
|
||||
"output": {
|
||||
"error": "login_failed" // <-- Your custom code
|
||||
},
|
||||
"failure_reason": "Login failed: The page displayed 'Invalid username or password'"
|
||||
}
|
||||
```
|
||||
|
||||
```json Webhook Payload
|
||||
{
|
||||
"run_id": "tsk_v2_486305187432193504",
|
||||
"status": "terminated",
|
||||
"output": {
|
||||
"error": "login_failed" // <-- Your custom code
|
||||
},
|
||||
"failure_reason": "Login failed: The page displayed 'Invalid username or password'",
|
||||
"webhook_callback_url": "https://your-server.com/webhook",
|
||||
"created_at": "2026-01-20T11:58:57.414123",
|
||||
"finished_at": "2026-01-20T12:00:31.512692"
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Both `output.error` (your code) and `failure_reason` (raw text) are present. Use `output.error` for branching, `failure_reason` for logging.
|
||||
|
||||
**Quick reference:** Where error codes appear
|
||||
|
||||
| Context | Field | Example |
|
||||
|---------|-------|---------|
|
||||
| Polling response | `run.output.error` | `run.output.get("error")` in Python |
|
||||
| Webhook payload | `output.error` | Same structure as polling |
|
||||
| Successful run | `output` contains your extracted data | No `error` key present |
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Respond in code
|
||||
|
||||
Now you can write clean switch/match logic:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key="your-api-key")
|
||||
|
||||
async def run_with_error_handling(retries=1):
|
||||
result = await client.run_task(
|
||||
prompt="Log in and download the invoice",
|
||||
url="https://vendor-portal.example.com",
|
||||
error_code_mapping={
|
||||
"login_failed": "Login credentials are incorrect or account is locked",
|
||||
"invoice_not_found": "No invoice for the requested date",
|
||||
"maintenance": "Site is down for maintenance"
|
||||
}
|
||||
)
|
||||
|
||||
run_id = result.run_id
|
||||
|
||||
# Poll until terminal state
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
await asyncio.sleep(5)
|
||||
|
||||
# Handle based on status and error code
|
||||
if run.status == "completed":
|
||||
return {"success": True, "data": run.output}
|
||||
|
||||
error_code = run.output.get("error") if run.output else None
|
||||
|
||||
if error_code == "login_failed":
|
||||
if retries > 0:
|
||||
await refresh_credentials("vendor-portal")
|
||||
return await run_with_error_handling(retries=retries - 1)
|
||||
return {"success": False, "reason": "login_failed", "details": "Retry limit reached"}
|
||||
|
||||
elif error_code == "invoice_not_found":
|
||||
# Expected condition: no invoice for this period
|
||||
return {"success": False, "reason": "no_invoice", "date": invoice_date}
|
||||
|
||||
elif error_code == "maintenance":
|
||||
# Schedule retry for later
|
||||
await schedule_retry(run_id, delay_minutes=60)
|
||||
return {"success": False, "reason": "scheduled_retry"}
|
||||
|
||||
else:
|
||||
# Unknown error: log and alert
|
||||
log_error(run_id, run.failure_reason)
|
||||
return {"success": False, "reason": "unknown", "details": run.failure_reason}
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
async function runWithErrorHandling(retries = 1) {
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Log in and download the invoice",
|
||||
url: "https://vendor-portal.example.com",
|
||||
error_code_mapping: {
|
||||
login_failed: "Login credentials are incorrect or account is locked",
|
||||
invoice_not_found: "No invoice for the requested date",
|
||||
maintenance: "Site is down for maintenance",
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
const runId = result.run_id;
|
||||
|
||||
// Poll until terminal state
|
||||
let run;
|
||||
while (true) {
|
||||
run = await client.getRun(runId);
|
||||
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
|
||||
break;
|
||||
}
|
||||
await new Promise((r) => setTimeout(r, 5000));
|
||||
}
|
||||
|
||||
// Handle based on status and error code
|
||||
if (run.status === "completed") {
|
||||
return { success: true, data: run.output };
|
||||
}
|
||||
|
||||
const errorCode = run.output?.error;
|
||||
|
||||
switch (errorCode) {
|
||||
case "login_failed":
|
||||
if (retries > 0) {
|
||||
await refreshCredentials("vendor-portal");
|
||||
return runWithErrorHandling(retries - 1);
|
||||
}
|
||||
return { success: false, reason: "login_failed", details: "Retry limit reached" };
|
||||
|
||||
case "invoice_not_found":
|
||||
return { success: false, reason: "no_invoice", date: invoiceDate };
|
||||
|
||||
case "maintenance":
|
||||
await scheduleRetry(runId, { delayMinutes: 60 });
|
||||
return { success: false, reason: "scheduled_retry" };
|
||||
|
||||
default:
|
||||
logError(runId, run.failure_reason);
|
||||
return { success: false, reason: "unknown", details: run.failure_reason };
|
||||
}
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Validation blocks as assertions
|
||||
|
||||
Validation blocks are assertions that check conditions at critical points, like unit test assertions. If validation fails, the workflow terminates immediately with your error code instead of continuing and failing later with a confusing error.
|
||||
|
||||
Use validation blocks after steps where you need to confirm success before proceeding:
|
||||
|
||||
<CodeGroup>
|
||||
```json JSON
|
||||
{
|
||||
"blocks": [
|
||||
{
|
||||
// First, attempt to log in
|
||||
"block_type": "navigation",
|
||||
"label": "login",
|
||||
"url": "https://vendor-portal.example.com/login",
|
||||
"navigation_goal": "Log in using stored credentials"
|
||||
},
|
||||
{
|
||||
// Then verify login succeeded before continuing
|
||||
"block_type": "validation",
|
||||
"label": "verify_login",
|
||||
"complete_criterion": "Dashboard or account overview page is visible",
|
||||
"terminate_criterion": "Login error message, CAPTCHA, or still on login page",
|
||||
"error_code_mapping": {
|
||||
"login_failed": "Login error message is displayed",
|
||||
"captcha_required": "CAPTCHA verification is shown",
|
||||
"session_expired": "Session timeout message appeared"
|
||||
}
|
||||
},
|
||||
{
|
||||
// Only runs if validation passed
|
||||
"block_type": "navigation",
|
||||
"label": "download_invoice",
|
||||
"navigation_goal": "Navigate to invoices and download {{invoice_date}}",
|
||||
"error_code_mapping": {
|
||||
"invoice_not_found": "No invoice for the specified date"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml YAML
|
||||
blocks:
|
||||
# First, attempt to log in
|
||||
- block_type: navigation
|
||||
label: login
|
||||
url: "https://vendor-portal.example.com/login"
|
||||
navigation_goal: "Log in using stored credentials"
|
||||
|
||||
# Then verify login succeeded before continuing
|
||||
- block_type: validation
|
||||
label: verify_login
|
||||
complete_criterion: "Dashboard or account overview page is visible"
|
||||
terminate_criterion: "Login error message, CAPTCHA, or still on login page"
|
||||
error_code_mapping:
|
||||
login_failed: "Login error message is displayed"
|
||||
captcha_required: "CAPTCHA verification is shown"
|
||||
session_expired: "Session timeout message appeared"
|
||||
|
||||
# Only runs if validation passed
|
||||
- block_type: navigation
|
||||
label: download_invoice
|
||||
navigation_goal: "Navigate to invoices and download {{invoice_date}}"
|
||||
error_code_mapping:
|
||||
invoice_not_found: "No invoice for the specified date"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Purpose |
|
||||
|-----------|---------|
|
||||
| `complete_criterion` | Condition that must be true to continue to the next block |
|
||||
| `terminate_criterion` | Condition that stops the workflow immediately |
|
||||
| `error_code_mapping` | Maps termination conditions to your error codes |
|
||||
|
||||
If `verify_login` sees a login error, the workflow terminates with `output.error = "login_failed"`. Your Step 4 code handles it the same way as any other error code.
|
||||
|
||||
---
|
||||
|
||||
## Common error patterns
|
||||
|
||||
| Error Code | Description | Typical Response |
|
||||
|------------|-------------|------------------|
|
||||
| `login_failed` | Credentials wrong, account locked, or MFA | Refresh credentials, retry |
|
||||
| `captcha_required` | CAPTCHA blocking automation | Use `human_interaction` block or browser profile |
|
||||
| `not_found` | Target data doesn't exist | Return empty result, don't retry |
|
||||
| `maintenance` | Site temporarily down | Schedule retry with backoff |
|
||||
| `rate_limited` | Too many requests | Add delays, use different proxy |
|
||||
| `access_denied` | Permission issue | Check account permissions |
|
||||
| `timeout` | Task took too long | Increase `max_steps`, simplify task |
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Reliability Tips"
|
||||
icon="shield-check"
|
||||
href="/developers/going-to-production/reliability-tips"
|
||||
>
|
||||
Write prompts that fail less often
|
||||
</Card>
|
||||
<Card
|
||||
title="Webhooks"
|
||||
icon="webhook"
|
||||
href="/developers/going-to-production/webhooks"
|
||||
>
|
||||
Get notified when runs complete or fail
|
||||
</Card>
|
||||
</CardGroup>
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,406 @@
|
||||
---
|
||||
title: Reliability Tips
|
||||
subtitle: Write robust prompts and handle edge cases
|
||||
description: Write robust prompts with clear completion criteria, choose the right block type for each step, handle dynamic pages and popups, and add validation blocks to catch errors before they cascade.
|
||||
slug: developers/going-to-production/reliability-tips
|
||||
keywords:
|
||||
- prompt engineering
|
||||
- completion criteria
|
||||
- block selection
|
||||
- dynamic pages
|
||||
- popups
|
||||
- validation block
|
||||
- edge cases
|
||||
- robust prompts
|
||||
---
|
||||
|
||||
The difference between a demo and production-ready automation is reliability. This page covers techniques for writing prompts that work consistently, handling dynamic pages, and validating results.
|
||||
|
||||
---
|
||||
|
||||
## Writing robust prompts
|
||||
|
||||
### Anatomy of a good prompt
|
||||
|
||||
Every prompt needs four components:
|
||||
|
||||
1. **Main goal** (required): What should happen
|
||||
2. **Guardrails**: Constraints and boundaries
|
||||
3. **Payload**: Data to use in form fields
|
||||
4. **Completion criteria** (required): How to know when done
|
||||
|
||||
```
|
||||
Your goal is to fill out the contact form with the provided information.
|
||||
Only fill out required fields. Skip optional fields unless you have data for them.
|
||||
|
||||
Here is the information:
|
||||
{{contact_data}}
|
||||
|
||||
COMPLETE when the form is submitted and you see a confirmation message.
|
||||
TERMINATE if you see an error message or the form cannot be submitted.
|
||||
```
|
||||
|
||||
### What works
|
||||
|
||||
**Be explicit about completion.** The AI needs to know when to stop. "COMPLETE when you see 'Order confirmed'" is unambiguous. Without this, the AI might keep navigating or stop too early.
|
||||
|
||||
<Tip>
|
||||
**Don't forget the submit button.** A common failure mode is the AI completing after filling form fields but before clicking Submit. Be explicit: "COMPLETE when you have clicked the Submit button AND see a confirmation message." The AI might consider the form "done" once all fields are filled, so make clear that submission is part of the goal.
|
||||
</Tip>
|
||||
|
||||
**Use visual descriptions.** "Click the blue Submit button at the bottom of the form" works better than "click Submit" because there might be multiple buttons, and visual context helps the AI pick the right one. Describe position, color, icons, and surrounding text.
|
||||
|
||||
**Start general, then refine.** Begin with simple prompts and add specifics based on failures. Over-specified prompts are brittle; the AI handles variation better when you describe goals rather than exact steps.
|
||||
|
||||
**Include termination criteria.** Tell the AI when to give up: "TERMINATE if login fails or account is locked." Without this, the AI might keep trying forever or fail silently.
|
||||
|
||||
**Reference visual indicators.** "The invoice download link has a PDF icon next to it" helps the AI identify the right element when there are multiple links with similar text.
|
||||
|
||||
### What doesn't work
|
||||
|
||||
**Vague goals.** "Do the thing on the website" gives the AI nothing to work with. Be specific about what outcome you want.
|
||||
|
||||
**Missing completion criteria.** Without knowing when to stop, the AI keeps navigating indefinitely or terminates at arbitrary points.
|
||||
|
||||
**Action lists without context.** "Click button A, then B, then C" breaks when the layout changes or buttons move. Describe the goal instead, and let the AI figure out the steps.
|
||||
|
||||
**HTML element names.** "Click the `<button id='submit'>` element" assumes IDs are stable and visible to the AI. They often change between deployments, and the AI works from visual screenshots, not DOM structure.
|
||||
|
||||
**Assuming page state.** The AI doesn't know what page you expect to be on. Always describe what you expect to see, not just what to do.
|
||||
|
||||
### Autocomplete and dropdown fields
|
||||
|
||||
Address fields, city selectors, and other autocomplete inputs are notoriously tricky. The AI might type a value, see suggestions appear, then second-guess itself, erasing and retyping, cycling through options like "Toronto" → "Ontario" → "Canada" → "Toronto" again before settling.
|
||||
|
||||
To reduce cycling behavior:
|
||||
|
||||
**Be explicit about the exact value.** Instead of "enter the city," say "type 'Toronto' and select it from the dropdown."
|
||||
|
||||
**Tell it to stop after selection.** Add "Once you've selected the value, move to the next field, and don't modify it further."
|
||||
|
||||
**Specify which suggestion to pick.** "Select the first suggestion that matches" or "Choose the option that shows the full address" reduces ambiguity.
|
||||
|
||||
```
|
||||
Fill in the shipping address:
|
||||
- For the City field, type "Toronto" and select the first matching suggestion
|
||||
- Do NOT cycle through suggestions or second-guess your selection
|
||||
- Once a field is filled, move to the next field immediately
|
||||
|
||||
{{address_data}}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Multi-select fields (where you pick several options from a list) are slower and less reliable than single-select. If the form allows it, consider making multiple API calls with single values rather than one call selecting many options.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Choosing the right block type
|
||||
|
||||
Skyvern offers three block types with different tradeoffs between reliability and flexibility. The more interpretation you ask the AI to do, the more room for unexpected behavior.
|
||||
|
||||
**Action blocks** are the most deterministic. You tell Skyvern exactly what to do: "Click the Submit button." There's no interpretation; it either finds the element and clicks it, or fails. Use these when you know exactly what action is needed and the page structure is predictable.
|
||||
|
||||
**Navigation blocks** give Skyvern a goal: "Fill out the registration form." The AI figures out which fields to fill and in what order. This handles variation in form layouts (fields might be in different positions, have different labels, or be split across tabs), but the AI can misinterpret ambiguous forms or fill fields you didn't intend.
|
||||
|
||||
**Task blocks (Navigation V2)** handle multi-step goals: "Log in, navigate to settings, update profile." Maximum flexibility for complex workflows, but more room for the AI to take unexpected paths. A task block might navigate through menus you didn't anticipate or skip steps it deems unnecessary.
|
||||
|
||||
<Warning>
|
||||
**Task blocks keep navigating until they believe the goal is complete.** If you want to click "Next" once and then stop, a Task block will likely click through ALL pages until it reaches the end. For single-action-then-stop behavior, use an Action block or Navigation block with explicit completion criteria like "COMPLETE after clicking Next once."
|
||||
</Warning>
|
||||
|
||||
**Rule of thumb:** Start with the most deterministic block that can accomplish your goal. If a single click solves the problem, don't use a Task block, because you're adding unnecessary interpretation where errors can creep in. Reserve Task blocks for genuinely multi-step workflows where you can't predict the exact sequence of actions.
|
||||
|
||||
---
|
||||
|
||||
## Handling dynamic pages
|
||||
|
||||
### Lazy-loaded content
|
||||
|
||||
For pages that load content as you scroll:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
prompt="Extract all product listings from the page",
|
||||
url="https://example.com/products",
|
||||
max_screenshot_scrolls=5 # Scroll to load more content
|
||||
)
|
||||
```
|
||||
|
||||
### Popups and modals
|
||||
|
||||
Include handling instructions in your prompt:
|
||||
|
||||
```
|
||||
Your goal is to add the item to cart.
|
||||
|
||||
If a popup appears asking about newsletter signup, close it by clicking the X.
|
||||
If a cookie consent banner appears, click Accept.
|
||||
|
||||
COMPLETE when the item is in the cart and the cart count increases.
|
||||
```
|
||||
|
||||
### Multi-step forms
|
||||
|
||||
For forms spread across multiple pages:
|
||||
|
||||
```
|
||||
Your goal is to complete the checkout process.
|
||||
|
||||
Page 1: Fill in shipping address using {{shipping_data}}
|
||||
Page 2: Select standard shipping
|
||||
Page 3: Enter payment details using {{payment_data}}
|
||||
Page 4: Review and submit
|
||||
|
||||
COMPLETE when you see the order confirmation number.
|
||||
TERMINATE if any validation error cannot be resolved.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation strategies
|
||||
|
||||
Workflows can silently produce wrong results. The AI might fill a form with incorrect data, navigate to the wrong page, or extract stale information. Validation blocks let you assert conditions at critical points and fail fast when something goes wrong, rather than discovering the problem downstream.
|
||||
|
||||
### Add validation blocks at critical points
|
||||
|
||||
**After login:** Verify you're actually authenticated before proceeding. A failed login might redirect to an error page or show a CAPTCHA, and subsequent blocks will fail in confusing ways if you don't catch this early.
|
||||
```yaml
|
||||
- block_type: validation
|
||||
label: verify_login_success
|
||||
complete_criterion: Dashboard or account page is visible
|
||||
terminate_criterion: Login error, CAPTCHA, or still on login page
|
||||
```
|
||||
|
||||
**Before form submission:** Catch data entry errors before they become permanent. The AI might have misinterpreted a field or filled in default values instead of your parameters.
|
||||
|
||||
```yaml
|
||||
- block_type: validation
|
||||
label: verify_form_data
|
||||
complete_criterion: |
|
||||
Review page shows correct values:
|
||||
- Name matches {{name}}
|
||||
- Email matches {{email}}
|
||||
terminate_criterion: Data mismatch or missing required fields
|
||||
```
|
||||
|
||||
### Use extraction to verify
|
||||
|
||||
For validation that requires exact matching (email addresses, confirmation numbers, prices), extract the values and compare programmatically in your code rather than relying on the AI's judgment:
|
||||
|
||||
```python
|
||||
result = await client.run_task(
|
||||
prompt="Fill out the form and extract the confirmation number",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"confirmation_number": {"type": "string"},
|
||||
"submitted_email": {"type": "string"}
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Verify in your code
|
||||
if result.output["submitted_email"] != expected_email:
|
||||
raise ValueError("Email mismatch")
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Validation blocks read from the current page, not from prior block outputs.** If you need to validate extracted data from a previous block, use a Code block to compare values programmatically. Validation blocks evaluate their criteria against what's visible on screen; they don't have access to data extracted by earlier extraction blocks.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Loop reliability
|
||||
|
||||
Loops are especially prone to cascading failures: when one iteration fails, it can leave the browser in an unexpected state that breaks subsequent iterations. For example, if iteration 3 navigates to an error page and fails, iteration 4 starts from that error page instead of the expected list view, causing it to fail too. One bad item can take down your entire loop.
|
||||
|
||||
Use a For Loop when you have a known list of items before the loop begins. Use a While Loop when the workflow should keep running until page state changes, such as paginating while a Next button is enabled or polling until a status changes. While loops need an especially clear exit condition because the number of iterations is discovered at run time.
|
||||
|
||||
### Always set `continue_on_failure`
|
||||
|
||||
```yaml
|
||||
- block_type: for_loop
|
||||
label: process_items
|
||||
loop_over_parameter_key: items_list
|
||||
continue_on_failure: true # Don't stop the whole loop if one item fails
|
||||
loop_blocks:
|
||||
- block_type: navigation
|
||||
label: process_item
|
||||
navigation_goal: "Process: {{ process_item.current_value }}"
|
||||
```
|
||||
|
||||
### Add a reset block
|
||||
|
||||
Each iteration should start from a known state. If iteration 3 fails on a detail page, iteration 4 needs to navigate back to the list before it can find its item. Add a reset block at the start of each loop iteration:
|
||||
|
||||
```yaml
|
||||
loop_blocks:
|
||||
- block_type: navigation
|
||||
label: reset_to_list
|
||||
url: "https://example.com/items"
|
||||
navigation_goal: "Navigate back to the items list"
|
||||
- block_type: navigation
|
||||
label: process_item
|
||||
navigation_goal: "Find and process: {{ process_item.current_value }}"
|
||||
```
|
||||
|
||||
For While Loop pagination, each pass should leave the page ready for the next condition check. Extract the state that controls the loop, then advance the page:
|
||||
|
||||
```yaml
|
||||
- block_type: while_loop
|
||||
label: paginate_results
|
||||
condition:
|
||||
criteria_type: jinja2_template
|
||||
expression: "{{ current_index == 0 or extract_page.has_next_page }}"
|
||||
loop_blocks:
|
||||
- block_type: extraction
|
||||
label: extract_page
|
||||
data_extraction_goal: Extract rows on this page and whether the Next button is enabled
|
||||
data_schema:
|
||||
type: object
|
||||
properties:
|
||||
rows:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
has_next_page:
|
||||
type: boolean
|
||||
- block_type: action
|
||||
label: click_next
|
||||
navigation_goal: "Click Next if it is enabled. COMPLETE after one click or if Next is disabled."
|
||||
```
|
||||
|
||||
The first condition check uses `current_index == 0` to enter the loop before `extract_page` exists. Later checks use the previous extraction output so the loop exits naturally when no next page is available.
|
||||
|
||||
### Include termination criteria per iteration
|
||||
|
||||
```yaml
|
||||
- block_type: navigation
|
||||
label: process_item
|
||||
navigation_goal: |
|
||||
Process the item: {{ process_item.current_value }}
|
||||
|
||||
COMPLETE when the item is processed.
|
||||
TERMINATE if you're not on the expected page or the item doesn't exist.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session timeouts and human-in-the-loop
|
||||
|
||||
Browser sessions have a default timeout. If you're using human-in-the-loop workflows where a person must approve an action before proceeding, the session can expire while waiting for approval, especially if the approver is slow or in a different timezone.
|
||||
|
||||
**Symptoms:** Runs that worked during testing fail in production with session expiry errors. The workflow waits for human approval, but by the time approval comes, the browser session has timed out.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Increase session timeout**: Set a longer `timeout` when creating browser sessions for workflows that include human approval steps
|
||||
2. **Remove the human step for time-sensitive flows**: If session expiry is causing failures, consider making the workflow fully automated and reviewing results after completion
|
||||
3. **Split into multiple workflows**: Run the pre-approval steps, wait for human approval outside Skyvern, then trigger a second workflow for post-approval steps using a browser profile to maintain login state
|
||||
|
||||
```python
|
||||
# Longer timeout for human-in-the-loop workflows
|
||||
session = await client.create_browser_session(
|
||||
timeout=300, # 5 minutes instead of default
|
||||
proxy_location="RESIDENTIAL"
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
For workflows with predictable human approval times, schedule runs to arrive in the approver's inbox during working hours when they can act quickly.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Keyboard actions and workarounds
|
||||
|
||||
<Note>
|
||||
Direct keyboard shortcuts (Ctrl+C, Alt+Tab, Esc, etc.) are not currently supported. Here are workarounds for common scenarios.
|
||||
</Note>
|
||||
|
||||
| Scenario | Workaround |
|
||||
|----------|------------|
|
||||
| **Copy text** | Use extraction block to get the text value |
|
||||
| **Paste into field** | Pass the value as a parameter: `{{value_to_paste}}` |
|
||||
| **Press Escape to close modal** | Click the X button or "Close" link instead. Add to prompt: "If a modal appears, close it by clicking the X button in the top right corner" |
|
||||
| **Keyboard navigation (Tab, arrows)** | Describe the click target visually instead |
|
||||
| **Ctrl+S to save** | Click the Save button in the UI, or look for auto-save indicators |
|
||||
| **Hotkey-only features** | Look for menu alternatives, toolbar buttons, or right-click context menus |
|
||||
| **Tab between fields** | AI handles field navigation automatically, so no workaround is needed |
|
||||
| **Enter to submit** | Explicitly click the Submit button rather than relying on Enter key |
|
||||
|
||||
For applications that genuinely require keyboard shortcuts with no UI alternative:
|
||||
|
||||
1. **Use the Code block** with custom Playwright scripts. You can call `page.keyboard.press('Escape')` directly
|
||||
2. **Check for an API**: Many web apps have APIs that bypass the UI entirely
|
||||
3. **Use browser profiles** with pre-configured settings or extensions that add UI buttons for keyboard-only features
|
||||
|
||||
```python
|
||||
# Example: Using Code block for keyboard actions
|
||||
- block_type: code
|
||||
label: press_escape
|
||||
code: |
|
||||
page = context["skyvern_page"].page
|
||||
await page.keyboard.press("Escape")
|
||||
result = {"escaped": True}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting workflow
|
||||
|
||||
When a run fails:
|
||||
|
||||
1. **Check the recording**: Watch what actually happened
|
||||
2. **Review screenshots**: See the state at each step
|
||||
3. **Check LLM reasoning**: Understand why the AI made each decision
|
||||
4. **Compare parameters**: Verify inputs match expectations
|
||||
|
||||
### Common fixes
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---------|--------------|-----|
|
||||
| **Completed too early** | Ambiguous completion criteria | Add specific visual indicators. Include "click Submit AND see confirmation" |
|
||||
| **Completed without submitting** | Submit button not included in goal | Explicitly state that clicking Submit is part of the task |
|
||||
| **Didn't complete** | Missing completion criteria | Add explicit COMPLETE condition |
|
||||
| **Wrong element clicked** | Multiple similar elements | Add distinguishing details: position, color, surrounding text |
|
||||
| **Form field skipped** | Field not visible or labeled differently | Describe the field's visual position |
|
||||
| **Loop stuck** | No reset between iterations | Add reset block at loop start |
|
||||
| **Autocomplete cycling** | AI second-guessing dropdown selections | Add "select and move on; don't modify" to prompt |
|
||||
| **Task navigates too far** | Task block continues until goal complete | Use Action/Navigation block for single-step actions |
|
||||
| **Session expired** | Human-in-the-loop timeout | Increase timeout or split into multiple workflows |
|
||||
| **Max steps reached** | Complex page or AI retrying actions | Increase `max_steps_per_run` or simplify the goal |
|
||||
|
||||
### When to adjust prompts vs file a bug
|
||||
|
||||
**Adjust your prompt if:**
|
||||
- The AI misunderstood what to do
|
||||
- Completion criteria were ambiguous
|
||||
- Visual descriptions were unclear
|
||||
|
||||
**File a bug if:**
|
||||
- Elements are visibly present but not detected
|
||||
- Actions execute on wrong elements consistently
|
||||
- Standard UI patterns (dropdowns, checkboxes) don't work
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Error Handling"
|
||||
icon="triangle-exclamation"
|
||||
href="/developers/going-to-production/error-handling"
|
||||
>
|
||||
Map errors to custom codes for programmatic handling
|
||||
</Card>
|
||||
<Card
|
||||
title="Workflow Blocks Reference"
|
||||
icon="cube"
|
||||
href="/cloud/building-workflows/configure-blocks"
|
||||
>
|
||||
Detailed documentation for validation and other blocks
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,540 @@
|
||||
---
|
||||
title: Webhooks
|
||||
subtitle: Get notified when tasks and workflows complete
|
||||
description: Configure webhook URLs for tasks and workflows to receive notifications when runs reach terminal status. Includes payload structure, HMAC-SHA256 signature verification, failure handling, and retry mechanisms.
|
||||
slug: developers/going-to-production/webhooks
|
||||
keywords:
|
||||
- webhook_url
|
||||
- HMAC-SHA256
|
||||
- signature verification
|
||||
- payload
|
||||
- callback
|
||||
- notification
|
||||
- retry
|
||||
- failure handling
|
||||
---
|
||||
|
||||
Workflows and task runs are asynchronous. When you call `run_task` or `run_workflow`, the API returns immediately with a run ID, but the actual execution happens in the background and can take variable time.
|
||||
|
||||
Instead of polling the `get_runs` endpoint, you can use Webhooks to get notified when they finish. Webhooks fire only when a run reaches a terminal status: `completed`, `failed`, `terminated`, `timed_out`, or `canceled`.
|
||||
|
||||
This page covers setting them up, explains payload structure, signature verification, and handling delivery failures.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Set webhook URL
|
||||
|
||||
### For tasks
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the price of this product",
|
||||
url="https://example.com/product/123",
|
||||
webhook_url="https://your-server.com/webhook",
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the price of this product",
|
||||
url: "https://example.com/product/123",
|
||||
webhook_url: "https://your-server.com/webhook",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the price of this product",
|
||||
"url": "https://example.com/product/123",
|
||||
"webhook_url": "https://your-server.com/webhook"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### For workflows
|
||||
Set a default webhook when creating the workflow, or override it per-run:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Set default on workflow (webhook_callback_url goes inside json_definition)
|
||||
workflow = await client.create_workflow(
|
||||
json_definition={
|
||||
"title": "Invoice Downloader",
|
||||
"webhook_callback_url": "https://your-server.com/webhook",
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "task",
|
||||
"label": "download_invoice",
|
||||
"url": "https://vendor-portal.example.com",
|
||||
"prompt": "Download the latest invoice"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Override for a specific run
|
||||
run = await client.run_workflow(
|
||||
workflow_id=workflow.workflow_permanent_id,
|
||||
parameters={},
|
||||
webhook_url="https://your-server.com/different-webhook"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Set default on workflow (webhook_callback_url goes inside json_definition)
|
||||
const workflow = await client.createWorkflow({
|
||||
body: {
|
||||
json_definition: {
|
||||
title: "Invoice Downloader",
|
||||
webhook_callback_url: "https://your-server.com/webhook",
|
||||
workflow_definition: {
|
||||
parameters: [],
|
||||
blocks: [
|
||||
{
|
||||
block_type: "task",
|
||||
label: "download_invoice",
|
||||
url: "https://vendor-portal.example.com",
|
||||
prompt: "Download the latest invoice",
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Override for a specific run
|
||||
const run = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: workflow.workflow_permanent_id,
|
||||
parameters: {},
|
||||
webhook_url: "https://your-server.com/different-webhook",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Set default on workflow (webhook_callback_url goes inside json_definition)
|
||||
curl -X POST "https://api.skyvern.com/v1/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"json_definition": {
|
||||
"title": "Invoice Downloader",
|
||||
"webhook_callback_url": "https://your-server.com/webhook",
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "task",
|
||||
"label": "download_invoice",
|
||||
"url": "https://vendor-portal.example.com",
|
||||
"prompt": "Download the latest invoice"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}'
|
||||
|
||||
# Override for a specific run (use workflow_permanent_id from create response)
|
||||
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"workflow_id": "wpid_123456789",
|
||||
"parameters": {},
|
||||
"webhook_url": "https://your-server.com/different-webhook"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
When creating a workflow, use `webhook_callback_url` inside `json_definition`; this sets the default for all runs. When running a workflow, use `webhook_url` at the top level to override for that specific run.
|
||||
</Info>
|
||||
|
||||
**Quick reference:**
|
||||
|
||||
| Context | Parameter | Location |
|
||||
|---------|-----------|----------|
|
||||
| Task run | `webhook_url` | Top-level parameter |
|
||||
| Workflow creation | `webhook_callback_url` | Inside `json_definition` |
|
||||
| Workflow run (override) | `webhook_url` | Top-level parameter |
|
||||
|
||||
<Warning>
|
||||
**Watch the parameter names.** Using `webhook_url` when creating a workflow (instead of `webhook_callback_url` inside `json_definition`) silently results in no webhook being sent. The API won't return an error. Your runs will just complete without notifications.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Understand the payload
|
||||
|
||||
Skyvern sends a JSON payload with run results. Here's a real example from a completed task:
|
||||
|
||||
**Webhook Payload:**
|
||||
```json
|
||||
{
|
||||
"run_id": "tsk_v2_490440779503357994",
|
||||
"task_id": "tsk_v2_490440779503357994",
|
||||
"status": "completed",
|
||||
"output": {
|
||||
"top_post_title": "Antirender: remove the glossy shine on architectural renderings"
|
||||
},
|
||||
"summary": "I have successfully retrieved the title of the top post from the Hacker News homepage.",
|
||||
"prompt": "Get the title of the top post on Hacker News",
|
||||
"url": "https://news.ycombinator.com/",
|
||||
"downloaded_files": [],
|
||||
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_490440844256003946/.../recording.webm?AWSAccessKeyId=...&Signature=...&Expires=...",
|
||||
"screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_490441394011816060/.../screenshot_final.png?AWSAccessKeyId=..."],
|
||||
"failure_reason": null,
|
||||
"errors": [],
|
||||
"step_count": 4,
|
||||
"run_type": "task_v2",
|
||||
"app_url": "https://app.skyvern.com/runs/wr_490440779503358000",
|
||||
"organization_id": "o_485917350850524254",
|
||||
"workflow_run_id": "wr_490440779503358000",
|
||||
"workflow_id": "w_490440779503357996",
|
||||
"workflow_permanent_id": "wpid_490440779503357998",
|
||||
"proxy_location": "RESIDENTIAL",
|
||||
"webhook_callback_url": "https://webhook.site/d8d013c1-0481-48d0-8d13-281e8563a508",
|
||||
"webhook_failure_reason": null,
|
||||
"created_at": "2026-01-31T15:20:42.160725",
|
||||
"modified_at": "2026-01-31T15:23:34.993138",
|
||||
"queued_at": "2026-01-31T15:20:42.371545",
|
||||
"started_at": "2026-01-31T15:20:44.391756",
|
||||
"finished_at": "2026-01-31T15:23:34.992815"
|
||||
}
|
||||
```
|
||||
|
||||
**Request Headers Sent:**
|
||||
```http
|
||||
POST /d8d013c1-0481-48d0-8d13-281e8563a508 HTTP/1.1
|
||||
Host: webhook.site
|
||||
Content-Type: application/json
|
||||
x-skyvern-signature: 024025ccf0bbfe1c8978bdaae43fc136fc8b614b92e2f63c3485be5a36866f68
|
||||
x-skyvern-timestamp: 1769873016
|
||||
Content-Length: 8208
|
||||
User-Agent: python-httpx/0.28.1
|
||||
|
||||
{...json payload above...}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `run_id` | string | Unique identifier for this run |
|
||||
| `task_id` | string | Same as `run_id` |
|
||||
| `status` | string | `completed`, `failed`, `terminated`, `timed_out`, or `canceled` |
|
||||
| `output` | object \| null | Extracted data from the task. If you configured [`error_code_mapping`](/developers/going-to-production/error-handling#step-3-use-error_code_mapping), failed runs include `output.error` with your custom error code. |
|
||||
| `summary` | string | AI-generated description of what was done |
|
||||
| `prompt` | string | The prompt from the original request |
|
||||
| `url` | string | The URL from the original request |
|
||||
| `downloaded_files` | array | Files downloaded during execution |
|
||||
| `recording_url` | string \| null | Video recording of the browser session |
|
||||
| `screenshot_urls` | array \| null | Screenshots captured (latest first) |
|
||||
| `failure_reason` | string \| null | Error message if the run failed |
|
||||
| `errors` | array | List of errors encountered |
|
||||
| `step_count` | integer \| null | Number of steps executed |
|
||||
| `run_type` | string | Type of run: `task_v2`, `openai_cua`, `anthropic_cua` |
|
||||
| `app_url` | string | Link to view this run in Skyvern Cloud |
|
||||
| `organization_id` | string | Your organization ID |
|
||||
| `workflow_run_id` | string | Associated workflow run ID |
|
||||
| `workflow_id` | string | Internal workflow ID |
|
||||
| `workflow_permanent_id` | string | Permanent workflow ID used to run the workflow |
|
||||
| `proxy_location` | string | Proxy location used (e.g., `RESIDENTIAL`) |
|
||||
| `webhook_callback_url` | string | The webhook URL that received this payload |
|
||||
| `webhook_failure_reason` | string \| null | Error message if a previous webhook delivery failed (always `null` in the payload you receive) |
|
||||
| `created_at` | datetime | When the run was created |
|
||||
| `modified_at` | datetime | When the run was last updated |
|
||||
| `queued_at` | datetime \| null | When the run entered the queue |
|
||||
| `started_at` | datetime \| null | When execution began |
|
||||
| `finished_at` | datetime \| null | When execution completed |
|
||||
|
||||
---
|
||||
|
||||
## Optional: Verify webhook signatures
|
||||
|
||||
Skyvern signs every webhook with your API key using HMAC-SHA256, so you can verify the request actually came from Skyvern before acting on it.
|
||||
|
||||
**Headers sent with every webhook:**
|
||||
- `x-skyvern-signature`: HMAC-SHA256 signature of the payload
|
||||
- `x-skyvern-timestamp`: Unix timestamp when the webhook was sent
|
||||
- `Content-Type: application/json`
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import hmac
|
||||
import hashlib
|
||||
from fastapi import Request, HTTPException
|
||||
|
||||
async def handle_webhook(request: Request):
|
||||
signature = request.headers.get("x-skyvern-signature")
|
||||
payload = await request.body()
|
||||
|
||||
expected = hmac.new(
|
||||
SKYVERN_API_KEY.encode("utf-8"),
|
||||
msg=payload,
|
||||
digestmod=hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
if not hmac.compare_digest(signature, expected):
|
||||
raise HTTPException(status_code=401, detail="Invalid signature")
|
||||
|
||||
data = await request.json()
|
||||
# Process the webhook...
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import crypto from "crypto";
|
||||
import express from "express";
|
||||
|
||||
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
|
||||
const signature = req.headers["x-skyvern-signature"];
|
||||
const payload = req.body;
|
||||
|
||||
const expected = crypto
|
||||
.createHmac("sha256", process.env.SKYVERN_API_KEY)
|
||||
.update(payload)
|
||||
.digest("hex");
|
||||
|
||||
// Use timing-safe comparison to prevent timing attacks
|
||||
let valid = false;
|
||||
try {
|
||||
crypto.timingSafeEqual(
|
||||
Buffer.from(signature || ''),
|
||||
Buffer.from(expected)
|
||||
);
|
||||
valid = true;
|
||||
} catch (err) {
|
||||
valid = false;
|
||||
}
|
||||
|
||||
if (!valid) {
|
||||
return res.status(401).send("Invalid signature");
|
||||
}
|
||||
|
||||
const data = JSON.parse(payload);
|
||||
// Process the webhook...
|
||||
res.status(200).send("OK");
|
||||
});
|
||||
```
|
||||
|
||||
```go Go
|
||||
package main
|
||||
|
||||
import (
|
||||
"crypto/hmac"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"io"
|
||||
"net/http"
|
||||
"os"
|
||||
)
|
||||
|
||||
func webhookHandler(w http.ResponseWriter, r *http.Request) {
|
||||
signature := r.Header.Get("x-skyvern-signature")
|
||||
payload, err := io.ReadAll(r.Body)
|
||||
if err != nil {
|
||||
http.Error(w, "Failed to read request body", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
mac := hmac.New(sha256.New, []byte(os.Getenv("SKYVERN_API_KEY")))
|
||||
mac.Write(payload)
|
||||
expected := hex.EncodeToString(mac.Sum(nil))
|
||||
|
||||
if !hmac.Equal([]byte(signature), []byte(expected)) {
|
||||
http.Error(w, "Invalid signature", http.StatusUnauthorized)
|
||||
return
|
||||
}
|
||||
|
||||
// Process the webhook...
|
||||
w.WriteHeader(http.StatusOK)
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
<Note>
|
||||
**Use constant-time comparison** to prevent timing attacks:
|
||||
- Python: `hmac.compare_digest()`
|
||||
- TypeScript: `crypto.timingSafeEqual()`
|
||||
- Go: `hmac.Equal()`
|
||||
|
||||
Never use simple equality operators (`==` or `===`) for signature comparison as they are vulnerable to timing attacks.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
**Always validate against the raw request body bytes.** Skyvern normalizes JSON before signing: it removes whitespace (using compact separators) and converts whole-number floats to integers (`3.0` becomes `3`). If you parse the JSON and re-serialize it, the byte representation will differ and signature validation will fail.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Handling webhook failures
|
||||
|
||||
Task execution and webhook delivery are independent; a task can succeed while webhook delivery fails. When this happens, the run shows `status: "failed"` even though your data was extracted successfully.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A["Run Finishes"] --> B{"Check status"}
|
||||
B -->|"completed"| C["Task succeeded<br>Webhook delivered"]
|
||||
B -->|"failed"| D{"Does failure_reason<br>mention 'webhook'?"}
|
||||
B -->|"terminated"| E["Goal unachievable"]
|
||||
D -->|"Yes"| F["Webhook delivery failed"]
|
||||
D -->|"No"| G["Task execution failed"]
|
||||
F --> H["Check output field<br>Data may still exist!"]
|
||||
G --> I["Check failure_reason"]
|
||||
C --> J["Process output"]
|
||||
|
||||
style A fill:#f8fafc,stroke:#6366F1,stroke-width:2px,color:#1e293b
|
||||
style B fill:#f8fafc,stroke:#6366F1,stroke-width:2px,color:#1e293b
|
||||
style C fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
|
||||
style D fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1e293b
|
||||
style E fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#475569
|
||||
style F fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
|
||||
style G fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b
|
||||
style H fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
|
||||
style I fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#475569
|
||||
style J fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
Webhook delivery can fail due to network issues, server errors, or misconfigured URLs.
|
||||
|
||||
When this happens, the run is marked as `failed` and the error is recorded in the `failure_reason` field. Check it by calling `get_run` after the run terminates:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status == "failed" and "webhook" in (run.failure_reason or "").lower():
|
||||
print(f"Webhook failed: {run.failure_reason}")
|
||||
# The task may have completed successfully before webhook delivery failed
|
||||
# Output data is still available
|
||||
if run.output:
|
||||
process_output(run.output)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (run.status === "failed" && run.failure_reason?.toLowerCase().includes("webhook")) {
|
||||
console.log(`Webhook failed: ${run.failure_reason}`);
|
||||
// The task may have completed successfully before webhook delivery failed
|
||||
// Output data is still available
|
||||
if (run.output) {
|
||||
processOutput(run.output);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
|
||||
# Check status and failure_reason fields in response
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The `failure_reason` field contains the specific error message, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "tsk_v2_486305187432193504",
|
||||
"status": "failed",
|
||||
"output": {"price": "$29.99"},
|
||||
"failure_reason": "Failed to run task 2.0: Failed to send webhook. task_v2_id=tsk_v2_486305187432193504"
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Even when webhook delivery fails, the task's `output` field may still contain extracted data if the browser automation completed successfully before the webhook attempt.
|
||||
</Note>
|
||||
|
||||
**Common reasons webhooks fail:**
|
||||
|
||||
- **Server unreachable**: Your server is down, behind a firewall, or the URL is incorrect. Verify the URL is publicly accessible (not `localhost`) and check your server logs for incoming requests.
|
||||
- **Timeout**: Skyvern waits 10 seconds for a response. If your server takes longer, the delivery is marked as failed even if processing eventually succeeds. Return `200 OK` immediately and process the payload in a background job.
|
||||
- **Server returns an error**: Your endpoint received the payload but responded with a non-2xx status code (e.g., 500). Check your server logs to identify the issue.
|
||||
- **Signature validation fails**: If your verification logic rejects the request, make sure you're validating against the raw request body, not parsed-and-re-serialized JSON (re-serializing changes the byte representation). Also verify you're using the same API key that created the run.
|
||||
|
||||
**Recommended pattern:** Always have a fallback polling mechanism for critical workflows. If you don't receive a webhook within your expected window, call `get_run` to check if the run completed and retrieve the data directly.
|
||||
|
||||
### Retrying webhooks
|
||||
|
||||
Once you've identified and fixed the issue, you can replay the webhook using `retry_run_webhook`.
|
||||
|
||||
<Note>
|
||||
Skyvern does not automatically retry failed webhooks. This is intentional: automatic retries can cause duplicate processing if your server received the payload but returned an error. You must explicitly call `retry_run_webhook` after fixing the issue.
|
||||
</Note>
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern.client import RetryRunWebhookRequest
|
||||
|
||||
await client.retry_run_webhook("tsk_v2_486305187432193504")
|
||||
|
||||
# Or send to a different URL
|
||||
await client.retry_run_webhook(
|
||||
"tsk_v2_486305187432193504",
|
||||
request=RetryRunWebhookRequest(webhook_url="https://your-server.com/new-webhook")
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await client.retryRunWebhook("tsk_v2_486305187432193504");
|
||||
|
||||
// Or send to a different URL
|
||||
await client.retryRunWebhook("tsk_v2_486305187432193504", {
|
||||
webhook_url: "https://your-server.com/new-webhook",
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/runs/tsk_v2_486305187432193504/retry_webhook" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
|
||||
# Or send to a different URL
|
||||
curl -X POST "https://api.skyvern.com/v1/runs/tsk_v2_486305187432193504/retry_webhook" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"webhook_url": "https://your-server.com/new-webhook"}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Warning>
|
||||
`retry_run_webhook` is fire-and-forget; it returns immediately without waiting for delivery confirmation. To verify success, monitor your webhook endpoint directly or check the run's `failure_reason` field after a short delay.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
**Implement idempotency.** If you call `retry_run_webhook`, you may receive the same payload twice (once from the original attempt that your server processed but returned an error, and once from the retry). Use the `run_id` as an idempotency key: check if you've already processed this run before taking action.
|
||||
</Tip>
|
||||
|
||||
You can pass a different `webhook_url` to send the payload to a new endpoint; useful if the original URL was misconfigured.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Error Handling"
|
||||
icon="triangle-exclamation"
|
||||
href="/developers/going-to-production/error-handling"
|
||||
>
|
||||
Handle failures and map custom error codes
|
||||
</Card>
|
||||
<Card
|
||||
title="Reliability Tips"
|
||||
icon="shield-check"
|
||||
href="/developers/going-to-production/reliability-tips"
|
||||
>
|
||||
Write robust prompts and add validation blocks
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,921 @@
|
||||
---
|
||||
title: Browser Profiles
|
||||
subtitle: Save and reuse authenticated browser state across runs
|
||||
description: Save browser state snapshots including cookies, localStorage, and session files as reusable profiles. Skip login steps and restore authenticated state instantly across workflow runs.
|
||||
slug: developers/optimization/browser-profiles
|
||||
keywords:
|
||||
- create_browser_profile
|
||||
- state snapshot
|
||||
- skip login
|
||||
- cookies
|
||||
- localStorage
|
||||
- session files
|
||||
- persist_browser_session
|
||||
---
|
||||
|
||||
A **Browser Profile** is a saved snapshot of browser state (cookies, localStorage, and session files) that you can reuse across multiple runs. Profiles let you skip login steps and restore authenticated state instantly.
|
||||
|
||||
Profiles are ideal when you:
|
||||
- Run the same workflow repeatedly with the same account (daily data extraction, scheduled reports)
|
||||
- Want multiple workflows to share the same authenticated state
|
||||
- Need to avoid repeated authentication to save time and steps
|
||||
|
||||
---
|
||||
|
||||
## How profiles work
|
||||
|
||||
When a workflow runs with `persist_browser_session=true`, Skyvern archives the browser state (cookies, storage, session files) after the run completes. This archiving happens asynchronously in the background. Once the archive is ready, you can create a profile from it, then pass that profile to future workflow runs to restore the saved state.
|
||||
|
||||
---
|
||||
|
||||
## Create a Browser Profile
|
||||
|
||||
Create a workflow with `persist_browser_session=true` in the workflow definition, run it, wait for completion, then create a profile from the run. Session archiving happens asynchronously, so add brief retry logic when creating the profile.
|
||||
|
||||
<Note>
|
||||
`persist_browser_session` must be set when **creating the workflow**, not when running it. It is a workflow definition property, not a runtime parameter.
|
||||
</Note>
|
||||
|
||||
### From a workflow run
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# Step 1: Create a workflow with persist_browser_session=true
|
||||
workflow = await client.create_workflow(
|
||||
json_definition={
|
||||
"title": "Login to Dashboard",
|
||||
"persist_browser_session": True, # Set here in workflow definition
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "login",
|
||||
"url": "https://dashboard.example.com/login",
|
||||
"navigation_goal": "Login with the provided credentials"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
)
|
||||
print(f"Created workflow: {workflow.workflow_permanent_id}")
|
||||
|
||||
# Step 2: Run the workflow
|
||||
workflow_run = await client.run_workflow(
|
||||
workflow_id=workflow.workflow_permanent_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(f"Workflow completed: {workflow_run.status}")
|
||||
|
||||
# Step 3: Create profile from the completed run
|
||||
# Retry briefly while session archives asynchronously
|
||||
for attempt in range(10):
|
||||
try:
|
||||
profile = await client.create_browser_profile(
|
||||
name="analytics-dashboard-login",
|
||||
workflow_run_id=workflow_run.run_id,
|
||||
description="Authenticated state for analytics dashboard",
|
||||
)
|
||||
print(f"Profile created: {profile.browser_profile_id}")
|
||||
break
|
||||
except Exception as e:
|
||||
if "persisted" in str(e).lower() and attempt < 9:
|
||||
await asyncio.sleep(1)
|
||||
continue
|
||||
raise
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
// Step 1: Create a workflow with persist_browser_session=true
|
||||
const workflow = await client.createWorkflow({
|
||||
body: {
|
||||
json_definition: {
|
||||
title: "Login to Dashboard",
|
||||
persist_browser_session: true, // Set here in workflow definition
|
||||
workflow_definition: {
|
||||
parameters: [],
|
||||
blocks: [
|
||||
{
|
||||
block_type: "navigation",
|
||||
label: "login",
|
||||
url: "https://dashboard.example.com/login",
|
||||
navigation_goal: "Login with the provided credentials"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
console.log(`Created workflow: ${workflow.workflow_permanent_id}`);
|
||||
|
||||
// Step 2: Run the workflow and wait for completion
|
||||
const workflowRun = await client.runWorkflow({
|
||||
body: { workflow_id: workflow.workflow_permanent_id },
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(`Workflow completed: ${workflowRun.status}`);
|
||||
|
||||
// Step 3: Create profile from the completed run
|
||||
let profile;
|
||||
for (let attempt = 0; attempt < 10; attempt++) {
|
||||
try {
|
||||
profile = await client.createBrowserProfile({
|
||||
name: "analytics-dashboard-login",
|
||||
workflow_run_id: workflowRun.run_id,
|
||||
description: "Authenticated state for analytics dashboard",
|
||||
});
|
||||
break;
|
||||
} catch (e) {
|
||||
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
|
||||
await new Promise((r) => setTimeout(r, 1000));
|
||||
continue;
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`Profile created: ${profile.browser_profile_id}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Step 1: Create a workflow with persist_browser_session=true
|
||||
WORKFLOW_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"json_definition": {
|
||||
"title": "Login to Dashboard",
|
||||
"persist_browser_session": true,
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "login",
|
||||
"url": "https://dashboard.example.com/login",
|
||||
"navigation_goal": "Login with the provided credentials"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}')
|
||||
|
||||
WORKFLOW_ID=$(echo "$WORKFLOW_RESPONSE" | jq -r '.workflow_permanent_id')
|
||||
echo "Created workflow: $WORKFLOW_ID"
|
||||
|
||||
# Step 2: Run the workflow
|
||||
RUN_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"workflow_id\": \"$WORKFLOW_ID\"}")
|
||||
|
||||
RUN_ID=$(echo "$RUN_RESPONSE" | jq -r '.run_id')
|
||||
|
||||
# Wait for completion
|
||||
while true; do
|
||||
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
|
||||
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
|
||||
sleep 5
|
||||
done
|
||||
|
||||
# Step 3: Create profile (retry while session archives)
|
||||
for i in {1..10}; do
|
||||
PROFILE_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"name\": \"analytics-dashboard-login\",
|
||||
\"workflow_run_id\": \"$RUN_ID\",
|
||||
\"description\": \"Authenticated state for analytics dashboard\"
|
||||
}")
|
||||
if echo "$PROFILE_RESPONSE" | jq -e '.browser_profile_id' > /dev/null 2>&1; then
|
||||
echo "$PROFILE_RESPONSE"
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `name` | string | Required. Display name for the profile. Must be unique within your organization |
|
||||
| `workflow_run_id` | string | ID of the completed workflow run to create the profile from |
|
||||
| `description` | string | Optional description of the profile's purpose |
|
||||
|
||||
### From a browser session
|
||||
|
||||
You can also create a profile from a [Browser Session](/developers/optimization/browser-sessions) that was used inside a workflow with `persist_browser_session=true`. After the workflow run completes and the session is closed, pass the session ID instead of the workflow run ID.
|
||||
|
||||
<Warning>
|
||||
Only sessions that were part of a workflow with `persist_browser_session=true` produce an archive. A session created with `create_browser_session()` alone does not archive its state. Archiving happens asynchronously after the session closes, so add retry logic.
|
||||
</Warning>
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# browser_session_id from a workflow run with persist_browser_session=true
|
||||
session_id = "pbs_your_session_id"
|
||||
|
||||
# Create profile from the closed session (retry while archive uploads)
|
||||
for attempt in range(10):
|
||||
try:
|
||||
profile = await client.create_browser_profile(
|
||||
name="dashboard-admin-login",
|
||||
browser_session_id=session_id,
|
||||
description="Admin account for dashboard access",
|
||||
)
|
||||
print(f"Profile created: {profile.browser_profile_id}")
|
||||
break
|
||||
except Exception as e:
|
||||
if "persisted" in str(e).lower() and attempt < 9:
|
||||
await asyncio.sleep(2)
|
||||
continue
|
||||
raise
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
// browser_session_id from a workflow run with persist_browser_session=true
|
||||
const sessionId = "pbs_your_session_id";
|
||||
|
||||
// Create profile from the closed session (retry while archive uploads)
|
||||
let profile;
|
||||
for (let attempt = 0; attempt < 10; attempt++) {
|
||||
try {
|
||||
profile = await client.createBrowserProfile({
|
||||
name: "dashboard-admin-login",
|
||||
browser_session_id: sessionId,
|
||||
description: "Admin account for dashboard access",
|
||||
});
|
||||
break;
|
||||
} catch (e) {
|
||||
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
|
||||
await new Promise((r) => setTimeout(r, 2000));
|
||||
continue;
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`Profile created: ${profile.browser_profile_id}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# browser_session_id from a workflow run with persist_browser_session=true
|
||||
SESSION_ID="pbs_your_session_id"
|
||||
|
||||
# Create profile (retry while session archives)
|
||||
for i in {1..10}; do
|
||||
PROFILE_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"name\": \"dashboard-admin-login\",
|
||||
\"browser_session_id\": \"$SESSION_ID\",
|
||||
\"description\": \"Admin account for dashboard access\"
|
||||
}")
|
||||
if echo "$PROFILE_RESPONSE" | jq -e '.browser_profile_id' > /dev/null 2>&1; then
|
||||
echo "$PROFILE_RESPONSE"
|
||||
break
|
||||
fi
|
||||
sleep 2
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `name` | string | Required. Display name for the profile. Must be unique within your organization |
|
||||
| `browser_session_id` | string | ID of the closed browser session (starts with `pbs_`). The session must have been part of a workflow with `persist_browser_session=true` |
|
||||
| `description` | string | Optional description of the profile's purpose |
|
||||
|
||||
---
|
||||
|
||||
## Use a Browser Profile
|
||||
|
||||
Pass `browser_profile_id` when running a workflow to restore the saved state. Skyvern restores cookies, localStorage, and session files before the first step runs.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# Run workflow with saved profile, no login needed
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wpid_daily_metrics",
|
||||
browser_profile_id="bp_490705123456789012",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
print(f"Output: {result.output}")
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
// Run workflow with saved profile, no login needed
|
||||
const result = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: "wpid_daily_metrics",
|
||||
browser_profile_id: "bp_490705123456789012",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
console.log(`Output: ${JSON.stringify(result.output)}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"workflow_id": "wpid_daily_metrics",
|
||||
"browser_profile_id": "bp_490705123456789012"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "wr_494469342201718946",
|
||||
"status": "created",
|
||||
"run_request": {
|
||||
"workflow_id": "wpid_daily_metrics",
|
||||
"browser_profile_id": "bp_490705123456789012",
|
||||
"proxy_location": "RESIDENTIAL"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
`browser_profile_id` is supported for workflows only. It is not available for standalone tasks via `run_task`. You also cannot use both `browser_profile_id` and `browser_session_id` in the same request.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Tutorial: save and reuse browsing state
|
||||
|
||||
This walkthrough demonstrates the full profile lifecycle: create a workflow that saves browser state, capture that state as a profile, then reuse it in a second workflow. Each step shows the code and the actual API response.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a workflow with persist_browser_session">
|
||||
|
||||
The workflow must have `persist_browser_session=true` so Skyvern archives the browser state after the run.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
workflow = await client.create_workflow(
|
||||
json_definition={
|
||||
"title": "Visit Hacker News",
|
||||
"persist_browser_session": True,
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "visit_hn",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"navigation_goal": "Navigate to the Hacker News homepage and confirm it loaded"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
)
|
||||
print(workflow.workflow_permanent_id) # wpid_494674198088536840
|
||||
print(workflow.persist_browser_session) # True
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const workflow = await client.createWorkflow({
|
||||
body: {
|
||||
json_definition: {
|
||||
title: "Visit Hacker News",
|
||||
persist_browser_session: true,
|
||||
workflow_definition: {
|
||||
parameters: [],
|
||||
blocks: [
|
||||
{
|
||||
block_type: "navigation",
|
||||
label: "visit_hn",
|
||||
url: "https://news.ycombinator.com",
|
||||
navigation_goal: "Navigate to the Hacker News homepage and confirm it loaded"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
console.log(workflow.workflow_permanent_id); // wpid_494674198088536840
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -s -X POST "https://api.skyvern.com/v1/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"json_definition": {
|
||||
"title": "Visit Hacker News",
|
||||
"persist_browser_session": true,
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [
|
||||
{
|
||||
"block_type": "navigation",
|
||||
"label": "visit_hn",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"navigation_goal": "Navigate to the Hacker News homepage and confirm it loaded"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```json Response
|
||||
{
|
||||
"workflow_permanent_id": "wpid_494674198088536840",
|
||||
"persist_browser_session": true,
|
||||
"title": "Visit Hacker News"
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Run the workflow">
|
||||
|
||||
Run the workflow and wait for it to complete. Skyvern opens a browser, executes the navigation block, then archives the browser state in the background.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
run = await client.run_workflow(
|
||||
workflow_id=workflow.workflow_permanent_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(run.run_id) # wr_494674202383504144
|
||||
print(run.status) # completed
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const run = await client.runWorkflow({
|
||||
body: { workflow_id: workflow.workflow_permanent_id },
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(run.run_id); // wr_494674202383504144
|
||||
console.log(run.status); // completed
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
RUN=$(curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"workflow_id\": \"$WORKFLOW_ID\"}")
|
||||
RUN_ID=$(echo "$RUN" | jq -r '.run_id')
|
||||
|
||||
# Poll until complete
|
||||
while true; do
|
||||
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
|
||||
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```json Response
|
||||
{
|
||||
"run_id": "wr_494674202383504144",
|
||||
"status": "completed"
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Create a profile from the completed run">
|
||||
|
||||
Archiving happens asynchronously after the run completes, so add retry logic. In practice the archive is usually ready within a few seconds.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
for attempt in range(10):
|
||||
try:
|
||||
profile = await client.create_browser_profile(
|
||||
name="hn-browsing-state",
|
||||
workflow_run_id=run.run_id,
|
||||
description="Hacker News cookies and browsing state",
|
||||
)
|
||||
print(profile.browser_profile_id) # bp_494674399951999772
|
||||
break
|
||||
except Exception as e:
|
||||
if "persisted" in str(e).lower() and attempt < 9:
|
||||
await asyncio.sleep(2)
|
||||
continue
|
||||
raise
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
let profile;
|
||||
for (let attempt = 0; attempt < 10; attempt++) {
|
||||
try {
|
||||
profile = await client.createBrowserProfile({
|
||||
name: "hn-browsing-state",
|
||||
workflow_run_id: run.run_id,
|
||||
description: "Hacker News cookies and browsing state",
|
||||
});
|
||||
console.log(profile.browser_profile_id); // bp_494674399951999772
|
||||
break;
|
||||
} catch (e) {
|
||||
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
|
||||
await new Promise((r) => setTimeout(r, 2000));
|
||||
continue;
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
for i in {1..10}; do
|
||||
PROFILE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"name\": \"hn-browsing-state\",
|
||||
\"workflow_run_id\": \"$RUN_ID\",
|
||||
\"description\": \"Hacker News cookies and browsing state\"
|
||||
}")
|
||||
PROFILE_ID=$(echo "$PROFILE" | jq -r '.browser_profile_id // empty')
|
||||
if [ -n "$PROFILE_ID" ]; then
|
||||
echo "$PROFILE" | jq .
|
||||
break
|
||||
fi
|
||||
sleep 2
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```json Response
|
||||
{
|
||||
"browser_profile_id": "bp_494674399951999772",
|
||||
"organization_id": "o_475582633898688888",
|
||||
"name": "hn-browsing-state",
|
||||
"description": "Hacker News cookies and browsing state",
|
||||
"created_at": "2026-02-12T01:09:18.048208",
|
||||
"modified_at": "2026-02-12T01:09:18.048212",
|
||||
"deleted_at": null
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify the profile exists">
|
||||
|
||||
List all profiles or fetch one by ID to confirm it was saved.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# List all profiles
|
||||
profiles = await client.list_browser_profiles()
|
||||
print(len(profiles)) # 1
|
||||
|
||||
# Get a single profile
|
||||
fetched = await client.get_browser_profile(profile_id=profile.browser_profile_id)
|
||||
print(fetched.name) # hn-browsing-state
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// List all profiles
|
||||
const profiles = await client.listBrowserProfiles({});
|
||||
console.log(profiles.length); // 1
|
||||
|
||||
// Get a single profile
|
||||
const fetched = await client.getBrowserProfile(profile.browser_profile_id);
|
||||
console.log(fetched.name); // hn-browsing-state
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# List all profiles
|
||||
curl -s "https://api.skyvern.com/v1/browser_profiles" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq '.[].name'
|
||||
|
||||
# Get a single profile
|
||||
curl -s "https://api.skyvern.com/v1/browser_profiles/$PROFILE_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq .
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```json List response
|
||||
[
|
||||
{
|
||||
"browser_profile_id": "bp_494674399951999772",
|
||||
"name": "hn-browsing-state",
|
||||
"created_at": "2026-02-12T01:09:18.048208"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Reuse the profile in a second workflow">
|
||||
|
||||
Pass `browser_profile_id` when running a workflow. Skyvern restores the saved cookies, localStorage, and session files before the first block runs. The second workflow starts with the browser state from step 2, no repeat navigation needed.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_workflow(
|
||||
workflow_id=data_workflow.workflow_permanent_id,
|
||||
browser_profile_id=profile.browser_profile_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(result.status) # completed
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: dataWorkflow.workflow_permanent_id,
|
||||
browser_profile_id: profile.browser_profile_id,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(result.status); // completed
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"workflow_id\": \"$WORKFLOW2_ID\",
|
||||
\"browser_profile_id\": \"$PROFILE_ID\"
|
||||
}"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```json Response
|
||||
{
|
||||
"run_id": "wr_494674434311738148",
|
||||
"status": "created"
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Delete the profile">
|
||||
|
||||
Clean up profiles you no longer need.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await client.delete_browser_profile(profile_id=profile.browser_profile_id)
|
||||
|
||||
# Confirm deletion
|
||||
remaining = await client.list_browser_profiles()
|
||||
print(len(remaining)) # 0
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await client.deleteBrowserProfile(profile.browser_profile_id);
|
||||
|
||||
// Confirm deletion
|
||||
const remaining = await client.listBrowserProfiles({});
|
||||
console.log(remaining.length); // 0
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -s -X DELETE "https://api.skyvern.com/v1/browser_profiles/$PROFILE_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
In a real scenario, step 1 would be a login workflow that authenticates with a site. The saved profile then lets all future workflows skip the login step entirely.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Best practices
|
||||
|
||||
### Use descriptive names
|
||||
|
||||
Include the account, site, and purpose in the profile name so it is easy to identify later.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Good: identifies account, site, and purpose
|
||||
profile = await client.create_browser_profile(
|
||||
name="prod-salesforce-admin",
|
||||
description="Admin login for daily opportunity sync",
|
||||
workflow_run_id=run_id,
|
||||
)
|
||||
|
||||
# Bad: unclear what this is for
|
||||
profile = await client.create_browser_profile(
|
||||
name="profile1",
|
||||
workflow_run_id=run_id,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Good: identifies account, site, and purpose
|
||||
const profile = await client.createBrowserProfile({
|
||||
name: "prod-salesforce-admin",
|
||||
description: "Admin login for daily opportunity sync",
|
||||
workflow_run_id: runId,
|
||||
});
|
||||
|
||||
// Bad: unclear what this is for
|
||||
const badProfile = await client.createBrowserProfile({
|
||||
name: "profile1",
|
||||
workflow_run_id: runId,
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Refresh profiles periodically
|
||||
|
||||
Session tokens and cookies expire. Re-run your login workflow and create fresh profiles before they go stale. Adding the date to the name makes it easy to track which profile is current.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from datetime import date
|
||||
|
||||
# Create dated profile after each successful login
|
||||
profile = await client.create_browser_profile(
|
||||
name=f"crm-login-{date.today()}",
|
||||
workflow_run_id=new_login_run.run_id,
|
||||
)
|
||||
|
||||
# Delete old profile
|
||||
await client.delete_browser_profile(old_profile_id)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Create dated profile after each successful login
|
||||
const profile = await client.createBrowserProfile({
|
||||
name: `crm-login-${new Date().toISOString().split("T")[0]}`,
|
||||
workflow_run_id: newLoginRun.run_id,
|
||||
});
|
||||
|
||||
// Delete old profile
|
||||
await client.deleteBrowserProfile(oldProfileId);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Create dated profile after a successful login run
|
||||
curl -X POST "https://api.skyvern.com/v1/browser_profiles" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"name\": \"crm-login-$(date +%Y-%m-%d)\",
|
||||
\"workflow_run_id\": \"$NEW_RUN_ID\"
|
||||
}"
|
||||
|
||||
# Delete old profile
|
||||
curl -X DELETE "https://api.skyvern.com/v1/browser_profiles/$OLD_PROFILE_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Capture updated state after each run
|
||||
|
||||
To capture state changes during a run (like token refreshes), the workflow must have `persist_browser_session=true` in its definition. This lets you create a fresh profile from each completed run.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from datetime import date
|
||||
|
||||
# Step 1: Create workflow with persist_browser_session in the definition
|
||||
workflow = await client.create_workflow(
|
||||
json_definition={
|
||||
"title": "Daily Sync",
|
||||
"persist_browser_session": True, # Set here, not in run_workflow
|
||||
"workflow_definition": {
|
||||
"parameters": [],
|
||||
"blocks": [...]
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Step 2: Run with an existing profile
|
||||
result = await client.run_workflow(
|
||||
workflow_id=workflow.workflow_permanent_id,
|
||||
browser_profile_id="bp_current",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
# Step 3: Create updated profile from the completed run
|
||||
if should_refresh_profile:
|
||||
new_profile = await client.create_browser_profile(
|
||||
name=f"daily-sync-{date.today()}",
|
||||
workflow_run_id=result.run_id,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Step 1: Create workflow with persist_browser_session in the definition
|
||||
const workflow = await client.createWorkflow({
|
||||
body: {
|
||||
json_definition: {
|
||||
title: "Daily Sync",
|
||||
persist_browser_session: true, // Set here, not in runWorkflow
|
||||
workflow_definition: {
|
||||
parameters: [],
|
||||
blocks: [/* ... */]
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Step 2: Run with an existing profile
|
||||
const result = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: workflow.workflow_permanent_id,
|
||||
browser_profile_id: "bp_current",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
// Step 3: Create updated profile from the completed run
|
||||
if (shouldRefreshProfile) {
|
||||
const newProfile = await client.createBrowserProfile({
|
||||
name: `daily-sync-${new Date().toISOString().split("T")[0]}`,
|
||||
workflow_run_id: result.run_id,
|
||||
});
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Browser Sessions"
|
||||
icon="browser"
|
||||
href="/developers/optimization/browser-sessions"
|
||||
>
|
||||
Maintain live browser state for real-time interactions
|
||||
</Card>
|
||||
<Card
|
||||
title="Cost Control"
|
||||
icon="dollar-sign"
|
||||
href="/developers/optimization/cost-control"
|
||||
>
|
||||
Optimize costs with max_steps and efficient prompts
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,726 @@
|
||||
---
|
||||
title: Browser Sessions
|
||||
subtitle: Persist live browser state across multiple tasks and workflows
|
||||
description: Create and manage live browser sessions that persist cookies, local storage, and page state between task or workflow runs. Use sessions for back-to-back tasks, human-in-the-loop approval, and real-time agents.
|
||||
slug: developers/optimization/browser-sessions
|
||||
keywords:
|
||||
- create_browser_session
|
||||
- persistent state
|
||||
- cookies
|
||||
- local storage
|
||||
- timeout
|
||||
- session chaining
|
||||
- human-in-the-loop
|
||||
- real-time agent
|
||||
---
|
||||
|
||||
A **Browser Session** is a live browser instance that persists cookies, local storage, and page state between task or workflow runs. Think of it as keeping a browser tab open. Use sessions when you need back-to-back tasks to share state, human-in-the-loop approval, or real-time agents.
|
||||
|
||||
---
|
||||
|
||||
## Create a session
|
||||
|
||||
Start a session with optional configuration for timeout, proxy, browser type, and extensions.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
session = await client.create_browser_session(
|
||||
timeout=60, # Max 60 minutes
|
||||
proxy_location="RESIDENTIAL", # US residential proxy
|
||||
browser_type="chrome", # Chrome or Edge
|
||||
extensions=["ad-blocker"], # Optional extensions
|
||||
)
|
||||
|
||||
print(f"Session ID: {session.browser_session_id}")
|
||||
print(f"Status: {session.status}")
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({
|
||||
apiKey: process.env.SKYVERN_API_KEY!,
|
||||
});
|
||||
|
||||
const session = await client.createBrowserSession({
|
||||
timeout: 60,
|
||||
proxy_location: "RESIDENTIAL",
|
||||
browser_type: "chrome",
|
||||
extensions: ["ad-blocker"],
|
||||
});
|
||||
|
||||
console.log(`Session ID: ${session.browser_session_id}`);
|
||||
console.log(`Status: ${session.status}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"timeout": 60,
|
||||
"proxy_location": "RESIDENTIAL",
|
||||
"browser_type": "chrome",
|
||||
"extensions": ["ad-blocker"]
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `timeout` | integer | Session lifetime in minutes. Min: 5, Max: 1440 (24 hours). Default: `60` |
|
||||
| `proxy_location` | string | Geographic proxy location (Cloud only). See [Proxy & Geolocation](/developers/going-to-production/proxy-geolocation) for available options |
|
||||
| `browser_type` | string | Browser type: `chrome` or `msedge` |
|
||||
| `extensions` | array | Extensions to install: `ad-blocker`, `captcha-solver` |
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"browser_session_id": "pbs_490705123456789012",
|
||||
"organization_id": "o_485917350850524254",
|
||||
"status": "running",
|
||||
"timeout": 60,
|
||||
"browser_type": "chrome",
|
||||
"extensions": ["ad-blocker"],
|
||||
"vnc_streaming_supported": true,
|
||||
"app_url": "https://app.skyvern.com/browser-session/pbs_490705123456789012",
|
||||
"started_at": "2026-02-01T10:30:03.110Z",
|
||||
"created_at": "2026-02-01T10:30:00.000Z",
|
||||
"modified_at": "2026-02-01T10:30:03.251Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Session statuses:**
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `running` | Browser is live and accepting tasks. This is the status returned on creation. The browser launches within seconds. |
|
||||
| `closed` | Session was closed manually or by timeout. No further tasks can run. |
|
||||
|
||||
<Warning>
|
||||
Sessions close automatically when the timeout expires, **even if a task is still running**. The timeout countdown begins when the browser launches. Set timeouts with enough margin for your longest expected task.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Run tasks with a session
|
||||
|
||||
Pass `browser_session_id` to `run_task` to execute tasks in an existing session. Each task continues from where the previous one left off: same page, same cookies, same form data.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# Create session
|
||||
session = await client.create_browser_session(timeout=30)
|
||||
session_id = session.browser_session_id
|
||||
|
||||
try:
|
||||
# Task 1: Login (wait for completion before continuing)
|
||||
await client.run_task(
|
||||
prompt="Login with username 'support@company.com'",
|
||||
url="https://dashboard.example.com/login",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
# Task 2: Search (already logged in from Task 1)
|
||||
result = await client.run_task(
|
||||
prompt="Find customer with email 'customer@example.com'",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
print(f"Customer: {result.output}")
|
||||
|
||||
finally:
|
||||
# Always close when done
|
||||
await client.close_browser_session(browser_session_id=session_id)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const session = await client.createBrowserSession({ timeout: 30 });
|
||||
const sessionId = session.browser_session_id;
|
||||
|
||||
try {
|
||||
// Task 1: Login (wait for completion)
|
||||
await client.runTask({
|
||||
body: {
|
||||
prompt: "Login with username 'support@company.com'",
|
||||
url: "https://dashboard.example.com/login",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
// Task 2: Search (reuses login state)
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Find customer with email 'customer@example.com'",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
console.log(`Customer: ${JSON.stringify(result.output)}`);
|
||||
|
||||
} finally {
|
||||
await client.closeBrowserSession(sessionId);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Create session
|
||||
SESSION_ID=$(curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"timeout": 30}' | jq -r '.browser_session_id')
|
||||
|
||||
echo "Session: $SESSION_ID"
|
||||
|
||||
# Task 1: Login
|
||||
RUN_ID=$(curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"prompt\": \"Login with username 'support@company.com'\",
|
||||
\"url\": \"https://dashboard.example.com/login\",
|
||||
\"browser_session_id\": \"$SESSION_ID\"
|
||||
}" | jq -r '.run_id')
|
||||
|
||||
# Poll until complete
|
||||
while true; do
|
||||
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
|
||||
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
|
||||
sleep 5
|
||||
done
|
||||
|
||||
# Task 2: Search (reuses login state)
|
||||
curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"prompt\": \"Find customer with email 'customer@example.com'\",
|
||||
\"browser_session_id\": \"$SESSION_ID\"
|
||||
}"
|
||||
|
||||
# Close session when done
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions/$SESSION_ID/close" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Run workflows with a session
|
||||
|
||||
Pass `browser_session_id` to `run_workflow` to execute a workflow in an existing session. This is useful when you need to run a predefined workflow but want it to continue from your current browser state.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# Create session
|
||||
session = await client.create_browser_session(timeout=60)
|
||||
session_id = session.browser_session_id
|
||||
|
||||
try:
|
||||
# First, login manually via a task
|
||||
await client.run_task(
|
||||
prompt="Login with username 'admin@company.com'",
|
||||
url="https://app.example.com/login",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
# Then run a workflow in the same session (already logged in)
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wpid_export_monthly_report",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
print(f"Workflow completed: {result.status}")
|
||||
|
||||
finally:
|
||||
await client.close_browser_session(browser_session_id=session_id)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const session = await client.createBrowserSession({ timeout: 60 });
|
||||
const sessionId = session.browser_session_id;
|
||||
|
||||
try {
|
||||
// First, login manually via a task
|
||||
await client.runTask({
|
||||
body: {
|
||||
prompt: "Login with username 'admin@company.com'",
|
||||
url: "https://app.example.com/login",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
// Then run a workflow in the same session (already logged in)
|
||||
const result = await client.runWorkflow({
|
||||
body: {
|
||||
workflow_id: "wpid_export_monthly_report",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
console.log(`Workflow completed: ${result.status}`);
|
||||
|
||||
} finally {
|
||||
await client.closeBrowserSession(sessionId);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Create session
|
||||
SESSION_ID=$(curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"timeout": 60}' | jq -r '.browser_session_id')
|
||||
|
||||
# Login via a task
|
||||
RUN_ID=$(curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"prompt\": \"Login with username 'admin@company.com'\",
|
||||
\"url\": \"https://app.example.com/login\",
|
||||
\"browser_session_id\": \"$SESSION_ID\"
|
||||
}" | jq -r '.run_id')
|
||||
|
||||
# Poll until login completes
|
||||
while true; do
|
||||
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
|
||||
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
|
||||
sleep 5
|
||||
done
|
||||
|
||||
# Run workflow in the same session (already logged in)
|
||||
curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"workflow_id\": \"wpid_export_monthly_report\",
|
||||
\"browser_session_id\": \"$SESSION_ID\"
|
||||
}"
|
||||
|
||||
# Close session when done
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions/$SESSION_ID/close" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
You cannot use both `browser_session_id` and `browser_profile_id` in the same request. Choose one or the other.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Close a session
|
||||
|
||||
Close a session to release resources and stop billing. The browser shuts down immediately.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await client.close_browser_session(
|
||||
browser_session_id="pbs_490705123456789012"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await client.closeBrowserSession("pbs_490705123456789012");
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/browser_sessions/pbs_490705123456789012/close" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Warning>
|
||||
**Always close sessions when done.** Active sessions continue billing even when idle. Use try/finally blocks to ensure cleanup.
|
||||
</Warning>
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
try:
|
||||
session = await client.create_browser_session(timeout=30)
|
||||
session_id = session.browser_session_id
|
||||
|
||||
# Do work...
|
||||
await client.run_task(
|
||||
prompt="...",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
finally:
|
||||
# Always close, even if task fails
|
||||
await client.close_browser_session(browser_session_id=session_id)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const session = await client.createBrowserSession({ timeout: 30 });
|
||||
const sessionId = session.browser_session_id;
|
||||
|
||||
try {
|
||||
await client.runTask({
|
||||
body: {
|
||||
prompt: "...",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
} finally {
|
||||
// Always close, even if task fails
|
||||
await client.closeBrowserSession(sessionId);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Example: Human-in-the-loop
|
||||
|
||||
A shopping bot that pauses for human approval before completing a purchase.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def shopping_with_approval():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
session = await client.create_browser_session(timeout=15)
|
||||
session_id = session.browser_session_id
|
||||
|
||||
try:
|
||||
# Step 1: Add to cart
|
||||
await client.run_task(
|
||||
prompt="Find wireless headphones under $100, add top result to cart",
|
||||
url="https://shop.example.com",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
# Step 2: Wait for human approval
|
||||
approval = input("Approve purchase? (yes/no): ")
|
||||
|
||||
if approval.lower() == "yes":
|
||||
# Step 3: Checkout (cart persists from Step 1)
|
||||
result = await client.run_task(
|
||||
prompt="Complete checkout and confirm order",
|
||||
browser_session_id=session_id,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(f"Order placed: {result.output}")
|
||||
else:
|
||||
print("Purchase cancelled")
|
||||
|
||||
finally:
|
||||
await client.close_browser_session(browser_session_id=session_id)
|
||||
|
||||
asyncio.run(shopping_with_approval())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
import * as readline from "readline";
|
||||
|
||||
async function shoppingWithApproval() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const session = await client.createBrowserSession({ timeout: 15 });
|
||||
const sessionId = session.browser_session_id;
|
||||
|
||||
try {
|
||||
// Step 1: Add to cart
|
||||
await client.runTask({
|
||||
body: {
|
||||
prompt: "Find wireless headphones under $100, add top result to cart",
|
||||
url: "https://shop.example.com",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
// Step 2: Wait for human approval
|
||||
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
|
||||
const approval = await new Promise<string>((resolve) =>
|
||||
rl.question("Approve purchase? (yes/no): ", resolve)
|
||||
);
|
||||
rl.close();
|
||||
|
||||
if (approval.toLowerCase() === "yes") {
|
||||
// Step 3: Checkout (cart persists from Step 1)
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Complete checkout and confirm order",
|
||||
browser_session_id: sessionId,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(`Order placed: ${JSON.stringify(result.output)}`);
|
||||
} else {
|
||||
console.log("Purchase cancelled");
|
||||
}
|
||||
|
||||
} finally {
|
||||
await client.closeBrowserSession(sessionId);
|
||||
}
|
||||
}
|
||||
|
||||
shoppingWithApproval();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The browser maintains the cart contents during the approval pause. No state is lost.
|
||||
|
||||
---
|
||||
|
||||
## Best practices
|
||||
|
||||
### Set appropriate timeouts
|
||||
|
||||
Sessions bill while open, so match the timeout to your use case. A task typically completes in 30 to 90 seconds, so a 10-minute timeout covers most multi-step sequences with margin. Human-in-the-loop flows need longer timeouts to account for wait time.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Quick multi-step task (2-3 tasks back to back)
|
||||
session = await client.create_browser_session(timeout=10)
|
||||
|
||||
# Human-in-the-loop with wait time for approval
|
||||
session = await client.create_browser_session(timeout=60)
|
||||
|
||||
# Long-running agent that monitors a dashboard
|
||||
session = await client.create_browser_session(timeout=480) # 8 hours
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Quick multi-step task (2-3 tasks back to back)
|
||||
const session1 = await client.createBrowserSession({ timeout: 10 });
|
||||
|
||||
// Human-in-the-loop with wait time for approval
|
||||
const session2 = await client.createBrowserSession({ timeout: 60 });
|
||||
|
||||
// Long-running agent that monitors a dashboard
|
||||
const session3 = await client.createBrowserSession({ timeout: 480 }); // 8 hours
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Quick multi-step task (2-3 tasks back to back)
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"timeout": 10}'
|
||||
|
||||
# Human-in-the-loop with wait time for approval
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"timeout": 60}'
|
||||
|
||||
# Long-running agent that monitors a dashboard
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"timeout": 480}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use workflows for predetermined sequences
|
||||
|
||||
If your steps don't need pauses between them, a workflow runs them in a single browser instance without the overhead of creating and managing a session. Each task in a session incurs its own startup cost, while workflow blocks share one browser.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Less efficient: multiple tasks in a session (each task has startup overhead)
|
||||
session = await client.create_browser_session()
|
||||
await client.run_task(prompt="Step 1", browser_session_id=session.browser_session_id, wait_for_completion=True)
|
||||
await client.run_task(prompt="Step 2", browser_session_id=session.browser_session_id, wait_for_completion=True)
|
||||
|
||||
# More efficient: single workflow (blocks share one browser, no inter-task overhead)
|
||||
await client.run_workflow(workflow_id="wpid_abc", wait_for_completion=True)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Less efficient: multiple tasks in a session (each task has startup overhead)
|
||||
const session = await client.createBrowserSession({});
|
||||
await client.runTask({ body: { prompt: "Step 1", browser_session_id: session.browser_session_id }, waitForCompletion: true });
|
||||
await client.runTask({ body: { prompt: "Step 2", browser_session_id: session.browser_session_id }, waitForCompletion: true });
|
||||
|
||||
// More efficient: single workflow (blocks share one browser, no inter-task overhead)
|
||||
await client.runWorkflow({ body: { workflow_id: "wpid_abc" }, waitForCompletion: true });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Choose the right browser type
|
||||
|
||||
Chrome has the widest compatibility. Use Edge only when a site requires or detects it specifically.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Chrome (default) - widest compatibility
|
||||
session = await client.create_browser_session(browser_type="chrome")
|
||||
|
||||
# Edge - for sites that require or fingerprint Edge
|
||||
session = await client.create_browser_session(browser_type="msedge")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Chrome (default) - widest compatibility
|
||||
const chromeSession = await client.createBrowserSession({ browser_type: "chrome" });
|
||||
|
||||
// Edge - for sites that require or fingerprint Edge
|
||||
const edgeSession = await client.createBrowserSession({ browser_type: "msedge" });
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Chrome (default) - widest compatibility
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"browser_type": "chrome"}'
|
||||
|
||||
# Edge - for sites that require or fingerprint Edge
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"browser_type": "msedge"}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use extensions strategically
|
||||
|
||||
Extensions add startup time, so only enable them when needed. The ad-blocker removes overlay ads that can interfere with automation. The captcha-solver handles CAPTCHAs automatically but is only available on Cloud.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Block ads that overlay content and interfere with clicks
|
||||
session = await client.create_browser_session(extensions=["ad-blocker"])
|
||||
|
||||
# Auto-solve captchas (Cloud only)
|
||||
session = await client.create_browser_session(extensions=["captcha-solver"])
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Block ads that overlay content and interfere with clicks
|
||||
const adBlockSession = await client.createBrowserSession({ extensions: ["ad-blocker"] });
|
||||
|
||||
// Auto-solve captchas (Cloud only)
|
||||
const captchaSession = await client.createBrowserSession({ extensions: ["captcha-solver"] });
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Block ads that overlay content and interfere with clicks
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"extensions": ["ad-blocker"]}'
|
||||
|
||||
# Auto-solve captchas (Cloud only)
|
||||
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"extensions": ["captcha-solver"]}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Sessions vs Profiles
|
||||
|
||||
Skyvern also offers [Browser Profiles](/developers/optimization/browser-profiles), saved snapshots of browser state (cookies, storage, session files) that you can reuse across days or weeks. Choose based on your use case:
|
||||
|
||||
| Aspect | Browser Session | Browser Profile |
|
||||
|--------|----------------|-----------------|
|
||||
| **What it is** | Live browser instance | Saved snapshot of browser state |
|
||||
| **Lifetime** | Minutes to hours | Days to months |
|
||||
| **State** | Current page, cookies, open connections | Cookies, storage, session files |
|
||||
| **Billing** | Charged while open | No cost when not in use |
|
||||
| **Best for** | Back-to-back tasks, human-in-the-loop, real-time agents | Repeated logins, scheduled workflows, shared auth state |
|
||||
|
||||
<Tip>
|
||||
You can create a [Browser Profile](/developers/optimization/browser-profiles) from a completed session to save its authenticated state for future reuse.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Connect Your Local Browser"
|
||||
icon="laptop"
|
||||
href="/developers/optimization/browser-tunneling"
|
||||
>
|
||||
Let Skyvern Cloud use your local browser with your existing logins
|
||||
</Card>
|
||||
<Card
|
||||
title="Browser Profiles"
|
||||
icon="floppy-disk"
|
||||
href="/developers/optimization/browser-profiles"
|
||||
>
|
||||
Save session state for reuse across days
|
||||
</Card>
|
||||
<Card
|
||||
title="Cost Control"
|
||||
icon="dollar-sign"
|
||||
href="/developers/optimization/cost-control"
|
||||
>
|
||||
Optimize costs with max_steps and efficient prompts
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,267 @@
|
||||
---
|
||||
title: Connect Skyvern to Your Local Browser
|
||||
subtitle: Run automations using your existing cookies, logins, and extensions
|
||||
description: Use skyvern browser serve to let Skyvern Cloud control a Chrome browser on your local machine, reusing your existing cookies, sessions, extensions, and saved passwords through a secure tunnel.
|
||||
slug: developers/optimization/browser-tunneling
|
||||
keywords:
|
||||
- browser session
|
||||
- task
|
||||
- CLI
|
||||
- authentication
|
||||
- login
|
||||
- proxy
|
||||
- Playwright
|
||||
---
|
||||
|
||||
Want Skyvern Cloud to automate a site where you're already logged in? With `skyvern browser serve`, Skyvern Cloud can control a Chrome browser running on your machine, using your existing cookies, sessions, extensions, and saved passwords.
|
||||
|
||||
**Common use cases:**
|
||||
- Automate sites where you're already authenticated (no need to re-login)
|
||||
- Reach internal tools behind a VPN or firewall
|
||||
- Use browser extensions you've already installed (ad blockers, auth tools, etc.)
|
||||
- Keep all browser data on your own machine
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
One command starts Chrome on your machine and creates a tunnel so Skyvern Cloud can connect:
|
||||
|
||||
```bash
|
||||
skyvern browser serve --tunnel
|
||||
```
|
||||
|
||||
That's it. The CLI launches Chrome, starts a local proxy server, and opens an ngrok tunnel. You'll see a tunnel URL in the output; pass it as `browser_address` when running tasks.
|
||||
|
||||
<Note>
|
||||
The `--tunnel` flag requires [ngrok](https://ngrok.com/download) to be installed and authenticated. Run `ngrok authtoken <your-token>` once to set it up.
|
||||
</Note>
|
||||
|
||||
### Step-by-step (manual tunnel)
|
||||
|
||||
If you prefer to manage the tunnel yourself:
|
||||
|
||||
```bash
|
||||
# 1. Start the browser server
|
||||
skyvern browser serve
|
||||
|
||||
# 2. In a separate terminal, create a tunnel
|
||||
ngrok http 9222
|
||||
|
||||
# 3. Copy the ngrok URL and use it as browser_address in your task
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Run a task on your local browser
|
||||
|
||||
Once the tunnel is running, pass the tunnel URL as `browser_address`:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
result = await client.run_task(
|
||||
prompt="Download the latest invoice from my account",
|
||||
browser_address="wss://abc123.ngrok-free.dev",
|
||||
)
|
||||
|
||||
print(f"Status: {result.status}")
|
||||
print(f"Output: {result.output}")
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Download the latest invoice from my account",
|
||||
browser_address: "wss://abc123.ngrok-free.dev",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
console.log(`Status: ${result.status}`);
|
||||
console.log(`Output: ${JSON.stringify(result.output)}`);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Download the latest invoice from my account",
|
||||
"browser_address": "wss://abc123.ngrok-free.dev"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ Your machine │
|
||||
│ │
|
||||
│ ┌────────────┐ CDP (internal) ┌──────────────┐ │
|
||||
│ │ Chrome │◄─────────────────►│ Unified │ │
|
||||
│ │ (port │ port 10222 │ Server │ │
|
||||
│ │ 10222) │ │ (port 9222) │ │
|
||||
│ └────────────┘ └──────┬───────┘ │
|
||||
│ │ │
|
||||
└──────────────────────────────────────────┼───────────┘
|
||||
│
|
||||
ngrok / tunnel│
|
||||
│
|
||||
┌──────▼───────┐
|
||||
│ Skyvern Cloud│
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
`skyvern browser serve`:
|
||||
|
||||
1. **Launches Chrome** with CDP (Chrome DevTools Protocol) enabled on an internal port
|
||||
2. **Starts a proxy server** on the exposed port (default `9222`) that forwards CDP traffic to Chrome
|
||||
3. **Optionally creates a tunnel** (`--tunnel`) so Skyvern Cloud can reach it from the internet
|
||||
|
||||
---
|
||||
|
||||
## CLI options
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `--port` | `9222` | Port for the proxy server. Chrome uses `port + 1000` internally. |
|
||||
| `--profile-dir` | `~/.skyvern/chrome-profile` | Chrome user data directory. Point this at an existing profile to reuse cookies and logins. |
|
||||
| `--download-dir` | `~/.skyvern/downloads/{browser_id}` | Directory for browser downloads. |
|
||||
| `--api-key` | (none) | API key for authenticating incoming requests. See [Security](#security). |
|
||||
| `--headless` | `false` | Run Chrome in headless mode (no visible window). |
|
||||
| `--chrome-path` | (auto-detect) | Path to Chrome/Chromium executable. |
|
||||
| `--tunnel` | `false` | Automatically start an ngrok tunnel. Requires `ngrok` installed. |
|
||||
| `--json` | `false` | Output connection info as JSON (for scripting). Cannot combine with `--tunnel`. |
|
||||
|
||||
The `--api-key` option can also be set via the `SKYVERN_BROWSER_SERVE_API_KEY` environment variable.
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Use a specific Chrome profile (reuse your existing logins)
|
||||
skyvern browser serve --profile-dir ~/Library/Application\ Support/Google/Chrome/Default
|
||||
|
||||
# Run headless with auto-tunnel
|
||||
skyvern browser serve --headless --tunnel
|
||||
|
||||
# Custom port with API key authentication
|
||||
skyvern browser serve --port 8222 --api-key "my-secret-key"
|
||||
|
||||
# Output connection info as JSON (useful for scripting)
|
||||
skyvern browser serve --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
<Warning>
|
||||
**Read this section before exposing your browser to the internet.**
|
||||
|
||||
When you run `skyvern browser serve` without `--api-key` and expose it via a tunnel, **anyone with the tunnel URL has full remote control of your Chrome browser**. This includes access to all logged-in sessions, cookies, saved passwords, and anything visible in the browser.
|
||||
</Warning>
|
||||
|
||||
### API key authentication
|
||||
|
||||
Use your Skyvern API key (from [Settings](https://app.skyvern.com/settings)) with the `--api-key` flag to require authentication on every incoming request:
|
||||
|
||||
```bash
|
||||
skyvern browser serve --api-key "your-skyvern-api-key"
|
||||
```
|
||||
|
||||
Or set it via environment variable:
|
||||
|
||||
```bash
|
||||
export SKYVERN_BROWSER_SERVE_API_KEY="your-skyvern-api-key"
|
||||
skyvern browser serve
|
||||
```
|
||||
|
||||
When enabled, all requests without a valid `x-api-key` header receive a `401 Unauthorized` response. Skyvern Cloud automatically sends the correct API key when connecting.
|
||||
|
||||
### Additional security measures
|
||||
|
||||
The built-in API key provides basic protection. For additional security such as IP allowlisting, mTLS, or VPN-based access, contact **support@skyvern.com**.
|
||||
|
||||
---
|
||||
|
||||
## When to use this vs other options
|
||||
|
||||
| Approach | When to use |
|
||||
|----------|-------------|
|
||||
| **Connect to your local browser** (`skyvern browser serve`) | You want Skyvern Cloud to use your local browser with your existing sessions |
|
||||
| **[Browser Sessions](/developers/optimization/browser-sessions)** | You want Skyvern Cloud to manage the browser entirely in the cloud |
|
||||
| **[Browser Profiles](/developers/optimization/browser-profiles)** | You want to save and reuse cookies/storage state across cloud sessions |
|
||||
| **[CDP Connect](/developers/self-hosted/browser#cdp-connect-external-chrome)** (self-hosted) | You're running Skyvern locally and want to connect to an existing Chrome instance |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="ngrok not found">
|
||||
Install ngrok from [ngrok.com/download](https://ngrok.com/download) and authenticate it:
|
||||
|
||||
```bash
|
||||
ngrok authtoken <your-token>
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Chrome not found">
|
||||
Use `--chrome-path` to specify the path to your Chrome executable:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
skyvern browser serve --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
|
||||
|
||||
# Linux
|
||||
skyvern browser serve --chrome-path /usr/bin/google-chrome
|
||||
|
||||
# Windows
|
||||
skyvern browser serve --chrome-path "C:\Program Files\Google\Chrome\Application\chrome.exe"
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Port already in use">
|
||||
Another process is using port 9222. Either stop that process or use a different port:
|
||||
|
||||
```bash
|
||||
skyvern browser serve --port 8222
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tunnel connection drops">
|
||||
ngrok free tier tunnels have connection limits. For production use, consider an ngrok paid plan or contact support@skyvern.com for alternative tunnel options.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Browser Sessions" icon="window" href="/developers/optimization/browser-sessions">
|
||||
Use cloud-managed browser sessions for multi-step tasks
|
||||
</Card>
|
||||
<Card title="Browser Profiles" icon="floppy-disk" href="/developers/optimization/browser-profiles">
|
||||
Save and reuse authenticated browser state
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,301 @@
|
||||
---
|
||||
title: Cost Control
|
||||
subtitle: Limit steps and optimize prompts to manage costs
|
||||
description: Control Skyvern costs using max_steps limits, code generation for repeatable tasks, cheaper engine tiers, and prompt optimization techniques to reduce step count and credit usage.
|
||||
slug: developers/optimization/cost-control
|
||||
keywords:
|
||||
- max_steps
|
||||
- credits
|
||||
- code generation
|
||||
- engine tier
|
||||
- prompt optimization
|
||||
- step count
|
||||
- budget
|
||||
---
|
||||
|
||||
Skyvern Cloud uses a **credit-based billing model**. Each plan includes a monthly credit allowance that determines how many actions you can run.
|
||||
|
||||
| Plan | Price | Actions Included |
|
||||
|------|-------|------------------|
|
||||
| Free | $0 | ~170 |
|
||||
| Hobby | $29 | ~1,200 |
|
||||
| Pro | $149 | ~6,200 |
|
||||
| Enterprise | Custom | Unlimited |
|
||||
|
||||
Use `max_steps` to limit steps per run and prevent runaway costs.
|
||||
|
||||
---
|
||||
|
||||
## Limit steps with max_steps
|
||||
|
||||
Set `max_steps` to cap the worst-case cost of any run. If a task gets stuck in a loop or hits repeated failures, `max_steps` stops it before it burns through your budget. The run terminates with `status: "timed_out"` when it hits the limit.
|
||||
|
||||
### For tasks
|
||||
|
||||
Pass `max_steps` in the request body.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
result = await client.run_task(
|
||||
prompt="Extract the top 3 products",
|
||||
url="https://example.com/products",
|
||||
max_steps=15,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(f"Steps taken: {result.step_count}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Extract the top 3 products",
|
||||
url: "https://example.com/products",
|
||||
max_steps: 15,
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(`Steps taken: ${result.step_count}`);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Extract the top 3 products",
|
||||
"url": "https://example.com/products",
|
||||
"max_steps": 15
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### For workflows
|
||||
|
||||
Pass `max_steps_override` as a parameter (Python) or `x-max-steps-override` header (TypeScript/cURL). This limits total steps across all blocks.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
result = await client.run_workflow(
|
||||
workflow_id="wf_data_extraction",
|
||||
max_steps_override=30,
|
||||
wait_for_completion=True,
|
||||
)
|
||||
print(f"Steps taken: {result.step_count}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const result = await client.runWorkflow({
|
||||
"x-max-steps-override": 30,
|
||||
body: { workflow_id: "wf_data_extraction" },
|
||||
waitForCompletion: true,
|
||||
});
|
||||
console.log(`Steps taken: ${result.step_count}`);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "x-max-steps-override: 30" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"workflow_id": "wf_data_extraction"}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
If runs consistently time out, increase `max_steps` or simplify the task. If `step_count` is much lower than `max_steps`, reduce the limit.
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## Use code generation for repeatable tasks
|
||||
|
||||
On Skyvern Cloud, the default **Skyvern 2.0 with Code** engine records the actions the AI takes and generates reusable code from them. Subsequent runs execute the generated code instead of the AI agent, skipping LLM inference and screenshot analysis entirely. This makes them faster, deterministic, and significantly cheaper.
|
||||
|
||||
1. Run your task with the default engine. Skyvern generates code from the recorded actions.
|
||||
2. Subsequent runs execute the cached code directly, no AI reasoning required.
|
||||
3. If the code doesn't handle an edge case, adjust your prompt and re-run to regenerate. Skyvern also falls back to the AI agent automatically if the cached code fails.
|
||||
|
||||
You can control this with the `run_with` parameter. Set it to `"code"` to use cached code, or `"agent"` to force AI reasoning.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
# First run: AI agent executes and generates code
|
||||
result = await client.run_task(
|
||||
prompt="Extract the top 3 products",
|
||||
url="https://example.com/products",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
|
||||
# Subsequent runs: execute cached code instead of AI
|
||||
result = await client.run_task(
|
||||
prompt="Extract the top 3 products",
|
||||
url="https://example.com/products",
|
||||
run_with="code",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
// First run: AI agent executes and generates code
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Extract the top 3 products",
|
||||
url: "https://example.com/products",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
|
||||
// Subsequent runs: execute cached code instead of AI
|
||||
const codeResult = await client.runTask({
|
||||
body: {
|
||||
prompt: "Extract the top 3 products",
|
||||
url: "https://example.com/products",
|
||||
run_with: "code",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# First run: AI agent executes and generates code
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Extract the top 3 products",
|
||||
"url": "https://example.com/products"
|
||||
}'
|
||||
|
||||
# Subsequent runs: execute cached code instead of AI
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Extract the top 3 products",
|
||||
"url": "https://example.com/products",
|
||||
"run_with": "code"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
Set `publish_workflow: true` to save the generated workflow so you can re-trigger it later or [schedule it on a recurring cron](/cloud/building-workflows/scheduling).
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Choose a cheaper engine
|
||||
|
||||
Not every task needs the most powerful engine. Use a lighter engine for simple, single-objective work.
|
||||
|
||||
| Engine | Cost | Best for |
|
||||
|--------|------|----------|
|
||||
| `skyvern-2.0` | Highest | Complex, multi-step tasks that require flexibility |
|
||||
| `skyvern-1.0` | Lower | Single-objective tasks like form fills or single-page extraction |
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key="YOUR_API_KEY")
|
||||
|
||||
result = await client.run_task(
|
||||
prompt="Fill out the contact form",
|
||||
url="https://example.com/contact",
|
||||
engine="skyvern-1.0",
|
||||
wait_for_completion=True,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
|
||||
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Fill out the contact form",
|
||||
url: "https://example.com/contact",
|
||||
engine: "skyvern-1.0",
|
||||
},
|
||||
waitForCompletion: true,
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Fill out the contact form",
|
||||
"url": "https://example.com/contact",
|
||||
"engine": "skyvern-1.0"
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
For self-hosted deployments, you can also swap the underlying LLM to a cheaper model (e.g., Gemini 2.5 Flash instead of a pro-tier model) via the `LLM_KEY` environment variable. See [LLM configuration](/developers/self-hosted/llm-configuration) for details.
|
||||
|
||||
---
|
||||
|
||||
## Write better prompts
|
||||
|
||||
Small prompt changes can cut step count significantly.
|
||||
|
||||
- **Be specific about the goal and completion criteria.** "Extract the price, title, and rating of the first 3 products" finishes faster than "look at the products page."
|
||||
- **Avoid open-ended exploration.** Prompts like "find interesting data" or "look around" cause the agent to wander.
|
||||
- **Use `data_extraction_schema`** to constrain what fields the AI extracts. This prevents it from spending steps parsing irrelevant content.
|
||||
- **Provide `url`** to start on the correct page instead of making the agent search for it.
|
||||
- **Use [browser profiles](/developers/optimization/browser-profiles)** to skip login steps on repeated runs.
|
||||
|
||||
---
|
||||
|
||||
## Monitor usage
|
||||
|
||||
- Check `step_count` in run responses to understand actual consumption per task.
|
||||
- Use `get_run_timeline()` to inspect individual steps and identify waste (loops, unnecessary navigation, retries).
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Browser Sessions"
|
||||
icon="browser"
|
||||
href="/developers/optimization/browser-sessions"
|
||||
>
|
||||
Maintain live browser state between calls
|
||||
</Card>
|
||||
<Card
|
||||
title="Browser Profiles"
|
||||
icon="floppy-disk"
|
||||
href="/developers/optimization/browser-profiles"
|
||||
>
|
||||
Save authenticated state for reuse across days
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,444 @@
|
||||
---
|
||||
title: Browser Configuration
|
||||
subtitle: Configure browser modes, display settings, and external Chrome connections
|
||||
description: Configure Skyvern's browser modes including headful, headless, local Chrome, and CDP connect. Set display resolution, viewport size, and connect to external Chrome instances for self-hosted deployments.
|
||||
slug: developers/self-hosted/browser
|
||||
keywords:
|
||||
- headless
|
||||
- headful
|
||||
- CDP
|
||||
- Chrome DevTools Protocol
|
||||
- display resolution
|
||||
- viewport
|
||||
- external Chrome
|
||||
- BROWSER_TYPE
|
||||
---
|
||||
|
||||
Skyvern uses Playwright with Chromium to execute browser automations.
|
||||
|
||||
## Browser modes
|
||||
|
||||
The `BROWSER_TYPE` setting controls how Skyvern runs the browser.
|
||||
|
||||
- **[Headful](#headful-default)**: visible browser window (default)
|
||||
- **[Headless](#headless)**: no display, runs in the background
|
||||
- **[Use Your Own Chrome](#use-your-own-chrome)**: runs the installed Chrome app with your logged-in profile
|
||||
- **[CDP Connect](#cdp-connect-external-chrome)**: connects to an already-running Chrome instance
|
||||
|
||||
### Headful (default)
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=chromium-headful
|
||||
```
|
||||
|
||||
The browser runs with a visible window. In Docker, this displays on a virtual framebuffer (Xvfb).
|
||||
|
||||
### Headless
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=chromium-headless
|
||||
```
|
||||
|
||||
The browser runs without any display.
|
||||
|
||||
<Note>
|
||||
Some websites detect and block headless browsers. If you encounter issues with bot detection, try headful mode with a virtual display.
|
||||
</Note>
|
||||
|
||||
### Use Your Own Chrome
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
|
||||
```
|
||||
|
||||
Skyvern launches the Chrome app installed on your machine and connects to it automatically. Your existing Chrome profile (cookies, saved logins, extensions) is copied over so automations run in a browser environment that matches your real one.
|
||||
|
||||
Useful for:
|
||||
- Running automations with your saved logins and cookies
|
||||
- Using your installed Chrome extensions
|
||||
- Avoiding bot detection by using a real Chrome installation
|
||||
|
||||
### CDP Connect (External Chrome)
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
|
||||
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
|
||||
```
|
||||
|
||||
Connect to an existing Chrome instance running with remote debugging enabled. Useful for:
|
||||
- Using your existing browser profile with saved logins
|
||||
- Debugging with Chrome DevTools
|
||||
- Running automations on a browser with specific extensions
|
||||
|
||||
<Note>
|
||||
Docker Compose self-host installs default `BROWSER_STREAMING_MODE` to `cdp`.
|
||||
Existing installs that already set this variable in `.env` keep their value.
|
||||
To opt out of CDP livestreaming, set `BROWSER_STREAMING_MODE=vnc` in `.env`.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Setting up Use Your Own Chrome
|
||||
|
||||
Set `CHROME_EXECUTABLE_PATH` to your Chrome installation path and Skyvern handles the rest. No need to manually start Chrome with debugging flags.
|
||||
|
||||
### Step 1: Find your Chrome path
|
||||
|
||||
<CodeGroup>
|
||||
```bash macOS
|
||||
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
|
||||
```
|
||||
|
||||
```powershell Windows
|
||||
"C:\Program Files\Google\Chrome\Application\chrome.exe"
|
||||
```
|
||||
|
||||
```bash Linux
|
||||
# Usually one of:
|
||||
/usr/bin/google-chrome
|
||||
/usr/bin/chromium
|
||||
/usr/bin/chromium-browser
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Step 2: Configure Skyvern
|
||||
|
||||
<CodeGroup>
|
||||
```bash macOS .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
|
||||
```
|
||||
|
||||
```bash Windows .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
CHROME_EXECUTABLE_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
|
||||
```
|
||||
|
||||
```bash Linux .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
CHROME_EXECUTABLE_PATH=/usr/bin/google-chrome
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
When Skyvern starts, it will:
|
||||
1. Copy your Chrome profile to a working directory (`./tmp/user_data_dir`)
|
||||
2. Launch Chrome with remote debugging on port 9222
|
||||
3. Connect via CDP automatically
|
||||
|
||||
<Warning>
|
||||
All existing Chrome windows must be closed before Skyvern can launch Chrome with remote debugging. If Chrome is already running, Skyvern will return an error.
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
If port 9222 is already in use (e.g., from a previous session), Skyvern will connect to the existing instance instead of launching a new one.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Setting up CDP Connect
|
||||
|
||||
CDP (Chrome DevTools Protocol) lets Skyvern control an external Chrome browser instead of launching its own.
|
||||
|
||||
### Step 1: Enable Chrome remote debugging
|
||||
|
||||
For an already-running Chrome profile, prefer Chrome's built-in remote debugging
|
||||
toggle:
|
||||
|
||||
1. Open `chrome://inspect/#remote-debugging` in Chrome.
|
||||
2. Enable remote debugging for this browser instance.
|
||||
3. Keep Chrome open while Skyvern connects.
|
||||
|
||||
This path keeps you on your existing Chrome profile. Skyvern will first try to
|
||||
auto-discover a local debugging server, then let you paste a direct
|
||||
`ws://.../devtools/browser/...` URL if Chrome exposes only a WebSocket endpoint.
|
||||
|
||||
#### Docker-reachable isolated profile fallback
|
||||
|
||||
When Skyvern runs in Docker, Chrome's built-in listener may bind to host
|
||||
loopback only. If the container cannot reach it, start a separate Chrome profile
|
||||
with a Docker-reachable CDP endpoint:
|
||||
|
||||
<CodeGroup>
|
||||
```bash macOS
|
||||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
|
||||
--remote-debugging-port=9222 \
|
||||
--remote-debugging-address=0.0.0.0 \
|
||||
--user-data-dir="$HOME/chrome-cdp-profile" \
|
||||
--no-first-run \
|
||||
--no-default-browser-check
|
||||
```
|
||||
|
||||
```powershell Windows
|
||||
"C:\Program Files\Google\Chrome\Application\chrome.exe" `
|
||||
--remote-debugging-port=9222 `
|
||||
--remote-debugging-address=0.0.0.0 `
|
||||
--user-data-dir="C:\chrome-cdp-profile" `
|
||||
--no-first-run `
|
||||
--no-default-browser-check
|
||||
```
|
||||
|
||||
```bash Linux
|
||||
google-chrome \
|
||||
--remote-debugging-port=9222 \
|
||||
--remote-debugging-address=0.0.0.0 \
|
||||
--user-data-dir="$HOME/chrome-cdp-profile" \
|
||||
--no-first-run \
|
||||
--no-default-browser-check
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The `--user-data-dir` flag creates a separate profile for Skyvern, preserving
|
||||
your main Chrome profile. Since [Chrome 136](https://developer.chrome.com/blog/remote-debugging-port),
|
||||
`--remote-debugging-port` is ignored for the default Chrome data directory, so
|
||||
only use these flags with a non-standard user data directory.
|
||||
|
||||
#### Windows Docker Desktop with `chrome://inspect`
|
||||
|
||||
Chrome's `chrome://inspect/#remote-debugging` toggle can bind its debugging
|
||||
server to host loopback only. Docker Desktop cannot connect to that listener
|
||||
directly through `host.docker.internal`. Skyvern includes a Windows helper that
|
||||
bridges Docker to Chrome and writes the exact WebSocket URL from Chrome's
|
||||
`DevToolsActivePort` file.
|
||||
|
||||
Open Chrome, go to `chrome://inspect/#remote-debugging`, enable remote
|
||||
debugging, then run this from an Administrator PowerShell in the Skyvern repo:
|
||||
|
||||
```powershell Windows
|
||||
.\scripts\windows_chrome_inspect_cdp.ps1 -UpdateEnv
|
||||
docker compose up -d --force-recreate skyvern
|
||||
```
|
||||
|
||||
The helper creates a Windows port proxy from `0.0.0.0:9223` to Chrome's
|
||||
loopback debugging port, adds a matching firewall rule, reads the full browser
|
||||
WebSocket path, and writes:
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
BROWSER_REMOTE_DEBUGGING_URL=ws://host.docker.internal:9223/devtools/browser/<id>
|
||||
BROWSER_REMOTE_DEBUGGING_HOST_HEADER=127.0.0.1:<chrome-port>
|
||||
BROWSER_STREAMING_MODE=cdp
|
||||
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
|
||||
```
|
||||
|
||||
Chrome may prompt you to allow the remote debugging connection the first time
|
||||
Skyvern connects. Click **Allow** and retry the browser session if the first
|
||||
attempt times out.
|
||||
|
||||
### Step 2: Configure Skyvern
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
|
||||
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
|
||||
```
|
||||
|
||||
Use the URL that matches the remote debugging path you chose. For a classic
|
||||
HTTP CDP endpoint, use the host and port. For a `chrome://inspect` flow that
|
||||
only exposes a browser WebSocket, use the full direct
|
||||
`ws://.../devtools/browser/<id>` URL.
|
||||
|
||||
When running Skyvern in Docker:
|
||||
|
||||
| Host OS | URL |
|
||||
|---------|-----|
|
||||
| macOS/Windows | `http://host.docker.internal:9222/` |
|
||||
| Linux | `http://172.17.0.1:9222/` |
|
||||
|
||||
If Docker Desktop reaches Chrome but Chrome rejects the `host.docker.internal`
|
||||
host name, Skyvern retries with the Docker host gateway IPv4 address. You can
|
||||
also set `BROWSER_REMOTE_DEBUGGING_URL` directly to that IPv4 address.
|
||||
|
||||
If Windows Defender Firewall blocks the connection from Docker, allow inbound
|
||||
TCP traffic on port 9222:
|
||||
|
||||
```powershell Windows
|
||||
New-NetFirewallRule -DisplayName "Chrome Remote Debug 9222" -Direction Inbound -LocalPort 9222 -Protocol TCP -Action Allow
|
||||
```
|
||||
|
||||
### Step 3: Verify connection
|
||||
|
||||
For a classic HTTP CDP endpoint, test that Chrome is listening on port 9222:
|
||||
|
||||
```bash
|
||||
curl http://localhost:9222/json/version
|
||||
```
|
||||
|
||||
```powershell Windows
|
||||
Invoke-RestMethod http://127.0.0.1:9222/json/version
|
||||
```
|
||||
|
||||
You should see Chrome's version information and a `webSocketDebuggerUrl`.
|
||||
|
||||
If you used the Windows `chrome://inspect` helper, the configured URL is a
|
||||
direct `ws://.../devtools/browser/<id>` endpoint. In that mode, verify by
|
||||
starting a Skyvern browser session after restarting the backend.
|
||||
|
||||
<Note>
|
||||
If `/json/version` does not return Chrome version information from inside the
|
||||
Skyvern container, verify Chrome is listening on `0.0.0.0:9222` or `::9222` and
|
||||
that Windows Firewall allows inbound traffic on port 9222.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
CDP mode exposes Chrome to network access. The examples use
|
||||
`--remote-debugging-address=0.0.0.0` so Docker can reach Chrome on the host.
|
||||
Only use this in trusted environments. If Skyvern runs on the same host outside
|
||||
Docker, bind to `127.0.0.1` instead.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Display settings
|
||||
|
||||
Configure how the browser appears to websites. These settings affect geolocation detection and content rendering.
|
||||
|
||||
### Locale and timezone
|
||||
|
||||
```bash .env
|
||||
# Optional, unset by default. Set to match your target region.
|
||||
BROWSER_LOCALE=en-US
|
||||
BROWSER_TIMEZONE=America/New_York
|
||||
```
|
||||
|
||||
Set these to match your target audience or the expected user location. Mismatched locale/timezone can trigger bot detection on some sites.
|
||||
|
||||
Common combinations:
|
||||
|
||||
| Region | BROWSER_LOCALE | BROWSER_TIMEZONE |
|
||||
|--------|----------------|------------------|
|
||||
| US East | `en-US` | `America/New_York` |
|
||||
| US West | `en-US` | `America/Los_Angeles` |
|
||||
| UK | `en-GB` | `Europe/London` |
|
||||
| Germany | `de-DE` | `Europe/Berlin` |
|
||||
| Japan | `ja-JP` | `Asia/Tokyo` |
|
||||
|
||||
### Viewport size
|
||||
|
||||
```bash .env
|
||||
BROWSER_WIDTH=1920
|
||||
BROWSER_HEIGHT=1080
|
||||
```
|
||||
|
||||
The default 1920x1080 works for most sites.
|
||||
|
||||
---
|
||||
|
||||
## Timeout settings
|
||||
|
||||
Control how long Skyvern waits for various browser operations.
|
||||
|
||||
```bash .env
|
||||
# Time to wait for individual actions (clicks, typing)
|
||||
BROWSER_ACTION_TIMEOUT_MS=5000
|
||||
|
||||
# Time to wait for screenshots to capture
|
||||
BROWSER_SCREENSHOT_TIMEOUT_MS=20000
|
||||
|
||||
# Time to wait for page loads
|
||||
BROWSER_LOADING_TIMEOUT_MS=60000
|
||||
|
||||
# Time to wait for DOM tree analysis
|
||||
BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS=60000
|
||||
```
|
||||
|
||||
### When to adjust timeouts
|
||||
|
||||
| Symptom | Adjustment |
|
||||
|---------|------------|
|
||||
| Actions fail on slow sites | Increase `BROWSER_ACTION_TIMEOUT_MS` |
|
||||
| Screenshots timeout on complex pages | Increase `BROWSER_SCREENSHOT_TIMEOUT_MS` |
|
||||
| Page load timeouts | Increase `BROWSER_LOADING_TIMEOUT_MS` |
|
||||
| DOM analysis fails on large pages | Increase `BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS` |
|
||||
|
||||
---
|
||||
|
||||
## Advanced settings
|
||||
|
||||
### Browser logging
|
||||
|
||||
```bash .env
|
||||
BROWSER_LOGS_ENABLED=true
|
||||
```
|
||||
|
||||
When enabled, browser console logs are captured in artifacts. Useful for debugging JavaScript errors on target sites.
|
||||
|
||||
### Maximum pages
|
||||
|
||||
```bash .env
|
||||
BROWSER_MAX_PAGES_NUMBER=10
|
||||
```
|
||||
|
||||
Limits the number of browser tabs Skyvern can open simultaneously. Increase if your workflows navigate multiple pages in parallel; decrease to reduce memory usage.
|
||||
|
||||
### Chrome policies
|
||||
|
||||
```bash .env
|
||||
BROWSER_POLICY_FILE=/etc/chromium/policies/managed/policies.json
|
||||
```
|
||||
|
||||
Path to a Chrome policy file for enterprise configurations.
|
||||
|
||||
### Video recording path
|
||||
|
||||
```bash .env
|
||||
VIDEO_PATH=./videos
|
||||
```
|
||||
|
||||
Directory where browser session recordings are saved. Recordings are useful for debugging but consume disk space.
|
||||
|
||||
---
|
||||
|
||||
## Memory considerations
|
||||
|
||||
Browser instances are memory-intensive. These are approximate guidelines. Actual usage depends on page complexity and browser settings.
|
||||
|
||||
| Concurrent tasks | Recommended RAM |
|
||||
|------------------|-----------------|
|
||||
| 1-2 | 4GB |
|
||||
| 3-5 | 8GB |
|
||||
| 6-10 | 16GB |
|
||||
| 10+ | 32GB+ |
|
||||
|
||||
If you experience out-of-memory errors:
|
||||
1. Reduce `BROWSER_MAX_PAGES_NUMBER`
|
||||
2. Use a smaller viewport (`BROWSER_WIDTH`, `BROWSER_HEIGHT`)
|
||||
3. Run in headless mode (`BROWSER_TYPE=chromium-headless`)
|
||||
4. Limit concurrent task execution
|
||||
|
||||
---
|
||||
|
||||
## Scaling browsers
|
||||
|
||||
The default Docker Compose setup runs one browser instance inside the Skyvern container. For higher concurrency:
|
||||
|
||||
### Option 1: Vertical scaling
|
||||
|
||||
Add more RAM to your server and increase `MAX_STEPS_PER_RUN` and `BROWSER_MAX_PAGES_NUMBER`.
|
||||
|
||||
### Option 2: Horizontal scaling
|
||||
|
||||
Deploy multiple Skyvern instances behind a load balancer. Each instance runs its own browser. See [Kubernetes Deployment](/developers/self-hosted/kubernetes) for orchestrated scaling.
|
||||
|
||||
### Option 3: External browser pool
|
||||
|
||||
Use a browser pool service like Browserless or your own Playwright grid, then connect via CDP:
|
||||
|
||||
```bash .env
|
||||
BROWSER_TYPE=cdp-connect
|
||||
BROWSER_REMOTE_DEBUGGING_URL=http://browserless:3000/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Proxy Setup" icon="shield" href="/developers/self-hosted/proxy">
|
||||
Configure proxies to avoid bot detection
|
||||
</Card>
|
||||
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
|
||||
Store recordings and artifacts in S3 or Azure Blob
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,404 @@
|
||||
---
|
||||
title: Docker Setup
|
||||
subtitle: Get Skyvern running in 10 minutes with Docker Compose
|
||||
description: Deploy Skyvern using Docker Compose with the API server, embedded browser, PostgreSQL database, and web UI. Includes LLM provider configuration and first-run setup.
|
||||
slug: developers/self-hosted/docker
|
||||
keywords:
|
||||
- Docker Compose
|
||||
- docker-compose.yml
|
||||
- PostgreSQL
|
||||
- environment variables
|
||||
- first-run
|
||||
- setup
|
||||
- .env
|
||||
---
|
||||
|
||||
This guide walks you through deploying Skyvern using Docker Compose. By the end, you'll have a working Skyvern instance with the API server, browser, database, and web UI running on your machine.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose v2 installed ([Get Docker](https://docs.docker.com/get-docker/)). All commands use `docker compose` (with a space). If you have an older installation, replace with `docker-compose`.
|
||||
- 4GB+ RAM available
|
||||
- An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Bedrock)
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Skyvern-AI/skyvern.git
|
||||
cd skyvern
|
||||
```
|
||||
|
||||
### 2. Configure environment variables
|
||||
|
||||
Copy the example environment file and configure your LLM provider:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Open `.env` and set your LLM provider. Here's an example for OpenAI:
|
||||
|
||||
```bash .env
|
||||
ENABLE_OPENAI=true
|
||||
OPENAI_API_KEY=sk-your-api-key-here
|
||||
LLM_KEY=OPENAI_GPT5_5
|
||||
```
|
||||
|
||||
For other providers, see [LLM Configuration](/developers/self-hosted/llm-configuration).
|
||||
|
||||
### 3. Configure the frontend
|
||||
|
||||
Copy the frontend environment file:
|
||||
|
||||
```bash
|
||||
cp skyvern-frontend/.env.example skyvern-frontend/.env
|
||||
```
|
||||
|
||||
The default values work for local development. Docker Compose mounts the generated local credentials into the UI container, so you can leave `VITE_SKYVERN_API_KEY` as `YOUR_API_KEY` for the first startup.
|
||||
|
||||
### 4. Start the services
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
This pulls the images and starts three services:
|
||||
- **postgres**: Database on port 5432 (internal only)
|
||||
- **skyvern**: API server on port 8000
|
||||
- **skyvern-ui**: Web interface on port 8080
|
||||
|
||||
First startup takes 1-2 minutes as it runs database migrations and creates your organization.
|
||||
|
||||
### 5. Get your API key
|
||||
|
||||
Wait for all services to be healthy before continuing:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
All three services should show `healthy` in the STATUS column. The `skyvern` container runs database migrations and generates credentials on first startup. This takes 1-2 minutes.
|
||||
|
||||
Once healthy, retrieve your API key:
|
||||
|
||||
```bash
|
||||
cat .skyvern/credentials.toml
|
||||
```
|
||||
|
||||
This file is auto-generated by Skyvern on first startup. The credentials inside are standard Skyvern API keys.
|
||||
|
||||
You'll see output like:
|
||||
|
||||
```toml
|
||||
[skyvern]
|
||||
configs = [
|
||||
{env = "local", host = "http://skyvern:8000/api/v1", orgs = [{name="Skyvern", cred="eyJhbGciOiJIUzI1..."}]}
|
||||
]
|
||||
```
|
||||
|
||||
The `host` value uses the Docker-internal hostname `skyvern`. From your machine, use `http://localhost:8000` instead. You only need the `cred` value. This is your API key.
|
||||
|
||||
### 6. Verify the installation
|
||||
|
||||
Open [http://localhost:8080](http://localhost:8080) in your browser. You should see the Skyvern dashboard.
|
||||
|
||||
Test the API by listing workflows (should return an empty array on fresh install):
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8000/v1/workflows \
|
||||
-H "x-api-key: YOUR_API_KEY_HERE"
|
||||
```
|
||||
|
||||
<Note>
|
||||
The API accepts requests on both `/v1/` and `/api/v1/`. The frontend uses `/api/v1` for backward compatibility. New integrations should use `/v1/`.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Understanding the services
|
||||
|
||||
The Docker Compose file defines three services that work together:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI[skyvern-ui<br/>:8080] --> API[skyvern<br/>:8000]
|
||||
API --> DB[(postgres<br/>:5432)]
|
||||
API --> Browser[Browser<br/>internal]
|
||||
API --> LLM[Your LLM<br/>Provider]
|
||||
```
|
||||
|
||||
| Service | Image | Ports | Purpose |
|
||||
|---------|-------|-------|---------|
|
||||
| `postgres` | postgres:14-alpine | 5432 (internal) | Stores tasks, workflows, credentials, and run history |
|
||||
| `skyvern` | public.ecr.aws/skyvern/skyvern | 8000, 9222 | API server + embedded browser |
|
||||
| `skyvern-ui` | public.ecr.aws/skyvern/skyvern-ui | 8080, 9090 | Web dashboard and artifact server |
|
||||
|
||||
The `skyvern` container includes Playwright with Chromium. The browser runs inside the same container as the API server. No separate browser service is needed.
|
||||
|
||||
### Data volumes
|
||||
|
||||
Docker Compose mounts several directories for persistent storage:
|
||||
|
||||
| Local path | Container path | Contents |
|
||||
|------------|----------------|----------|
|
||||
| `./postgres-data` | `/var/lib/postgresql/data` | Database files |
|
||||
| `./artifacts` | `/data/artifacts` | Extracted data, screenshots |
|
||||
| `./videos` | `/data/videos` | Browser session recordings |
|
||||
| `./har` | `/data/har` | HTTP Archive files for debugging |
|
||||
| `./log` | `/data/log` | Application logs |
|
||||
| `./.skyvern` | `/app/.skyvern` | Generated API credentials |
|
||||
|
||||
---
|
||||
|
||||
## Environment variables reference
|
||||
|
||||
The `.env` file controls the Skyvern server. Here are the most important variables grouped by purpose.
|
||||
|
||||
### Environment files
|
||||
|
||||
`docker-compose.yml` uses TWO sources for service environment:
|
||||
|
||||
1. **Inline `environment:` block** — compose-network values that depend on the docker network topology. Examples: `DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern` (the `postgres` hostname only resolves inside the compose network), `BROWSER_TYPE`, `BROWSER_STREAMING_MODE`, `ENABLE_CODE_BLOCK`.
|
||||
|
||||
2. **`env_file: .env`** — user secrets (LLM API keys, etc.).
|
||||
|
||||
**Do not move `DATABASE_STRING` from compose into `.env`.** The `.env.example` shipped with the repo uses a `localhost` host that points at the backend container itself when used inside compose — moving that value into `.env` will break the database connection.
|
||||
|
||||
If you have an existing `.env` from a pre-1.0.32 `skyvern quickstart` run, it may contain a leftover `DATABASE_STRING=postgresql+psycopg://skyvern@localhost/skyvern` line. Remove it:
|
||||
|
||||
```bash
|
||||
sed -i.bak '/^DATABASE_STRING.*localhost/d' .env
|
||||
```
|
||||
|
||||
### LLM Configuration
|
||||
|
||||
Configure at least one LLM provider. See [LLM Configuration](/developers/self-hosted/llm-configuration) for all providers.
|
||||
|
||||
```bash
|
||||
# OpenAI
|
||||
ENABLE_OPENAI=true
|
||||
OPENAI_API_KEY=sk-...
|
||||
LLM_KEY=OPENAI_GPT5_5
|
||||
|
||||
# Or Anthropic
|
||||
ENABLE_ANTHROPIC=true
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
|
||||
```
|
||||
|
||||
### Browser settings
|
||||
|
||||
```bash
|
||||
# Browser mode: chromium-headful (visible) or chromium-headless (no display)
|
||||
BROWSER_TYPE=chromium-headful
|
||||
|
||||
# Browser livestreaming mode: cdp (default local screencast) or vnc
|
||||
BROWSER_STREAMING_MODE=cdp
|
||||
|
||||
# Timeout for individual browser actions (milliseconds)
|
||||
BROWSER_ACTION_TIMEOUT_MS=5000
|
||||
|
||||
# Where to save recordings
|
||||
VIDEO_PATH=./videos
|
||||
```
|
||||
|
||||
### Task execution
|
||||
|
||||
```bash
|
||||
# Maximum steps before a task times out
|
||||
MAX_STEPS_PER_RUN=10
|
||||
|
||||
# Server port
|
||||
PORT=8000
|
||||
|
||||
# Log verbosity: DEBUG, INFO, WARNING, ERROR
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### Database
|
||||
|
||||
The database connection is set in `docker-compose.yml`, not `.env`:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern
|
||||
```
|
||||
|
||||
To use an external database, update this connection string and remove the `postgres` service.
|
||||
|
||||
---
|
||||
|
||||
## Common operations
|
||||
|
||||
### View logs
|
||||
|
||||
```bash
|
||||
# All services
|
||||
docker compose logs -f
|
||||
|
||||
# Specific service
|
||||
docker compose logs -f skyvern
|
||||
```
|
||||
|
||||
### Restart after configuration changes
|
||||
|
||||
```bash
|
||||
docker compose restart skyvern
|
||||
```
|
||||
|
||||
### Stop all services
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Update to latest version
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Reset everything (including database)
|
||||
|
||||
<Warning>
|
||||
This deletes all data including task history, credentials, and recordings.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
rm -rf postgres-data artifacts videos har log .skyvern
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exposing to the network
|
||||
|
||||
By default, Skyvern only accepts connections from localhost. To expose it on your network:
|
||||
|
||||
### Option 1: Bind to all interfaces
|
||||
|
||||
Edit `docker-compose.yml` to change the port bindings:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
skyvern:
|
||||
ports:
|
||||
- "0.0.0.0:8000:8000" # Accept connections from any IP
|
||||
```
|
||||
|
||||
### Option 2: Use a reverse proxy
|
||||
|
||||
For production deployments, put Skyvern behind nginx or Traefik:
|
||||
|
||||
```
|
||||
your-domain.com → nginx → localhost:8080 (UI)
|
||||
api.your-domain.com → nginx → localhost:8000 (API)
|
||||
```
|
||||
|
||||
Update the frontend environment to use your domain:
|
||||
|
||||
```bash skyvern-frontend/.env
|
||||
VITE_API_BASE_URL=https://api.your-domain.com/api/v1
|
||||
VITE_WSS_BASE_URL=wss://api.your-domain.com/api/v1
|
||||
VITE_ARTIFACT_API_BASE_URL=https://artifacts.your-domain.com
|
||||
```
|
||||
|
||||
<Warning>
|
||||
If exposing Skyvern to the internet, add authentication at the reverse proxy layer or use a VPN.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Container exits immediately">
|
||||
Check the logs for the failing service:
|
||||
|
||||
```bash
|
||||
docker compose logs skyvern
|
||||
```
|
||||
|
||||
Common causes:
|
||||
- Missing or invalid LLM API key: look for LLM-related errors in logs
|
||||
- Database connection failed: check if `postgres` service is healthy with `docker compose ps`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='API returns "Invalid credentials" (403)'>
|
||||
The API key is missing, malformed, or doesn't match the organization. Verify:
|
||||
|
||||
1. The `x-api-key` header is included in your request
|
||||
2. The key matches exactly what's in `.skyvern/credentials.toml`
|
||||
3. No extra whitespace or newlines in the key
|
||||
|
||||
```bash
|
||||
# Correct format
|
||||
curl -H "x-api-key: eyJhbGciOiJIUzI1..." http://localhost:8000/v1/workflows
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='API returns "Could not validate credentials" (403)'>
|
||||
The API key format is invalid (JWT decode failed). This usually means:
|
||||
- The key was truncated or corrupted during copy-paste
|
||||
- You're using an API key from a different Skyvern installation
|
||||
|
||||
Regenerate credentials by resetting the installation:
|
||||
|
||||
```bash
|
||||
rm -rf .skyvern
|
||||
docker compose restart skyvern
|
||||
cat .skyvern/credentials.toml # Get new key
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="UI shows blank page or connection errors">
|
||||
Check that `skyvern-frontend/.env` has the correct values:
|
||||
|
||||
```bash
|
||||
VITE_API_BASE_URL=http://localhost:8000/api/v1
|
||||
VITE_WSS_BASE_URL=ws://localhost:8000/api/v1
|
||||
VITE_SKYVERN_API_KEY=<your-key-from-credentials.toml>
|
||||
```
|
||||
|
||||
After updating, restart the UI:
|
||||
|
||||
```bash
|
||||
docker compose restart skyvern-ui
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Task fails with "Unknown browser type"'>
|
||||
The `BROWSER_TYPE` environment variable has an invalid value. Valid options:
|
||||
- `chromium-headful`: Browser with visible window (default)
|
||||
- `chromium-headless`: No visible window
|
||||
- `cdp-connect`: Connect to external Chrome
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Task fails with "Context window exceeded"'>
|
||||
The page content is too large for the LLM. Try:
|
||||
- Simplifying your prompt
|
||||
- Starting from a more specific URL
|
||||
- Using a model with a larger context window
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="LLM Configuration" icon="microchip" href="/developers/self-hosted/llm-configuration">
|
||||
Configure OpenAI, Anthropic, Azure, Ollama, and other providers
|
||||
</Card>
|
||||
<Card title="Browser Configuration" icon="window" href="/developers/self-hosted/browser">
|
||||
Customize browser settings, locales, and connect to external Chrome
|
||||
</Card>
|
||||
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
|
||||
Store artifacts in S3 or Azure Blob instead of local disk
|
||||
</Card>
|
||||
<Card title="Proxy Setup" icon="shield" href="/developers/self-hosted/proxy">
|
||||
Configure proxies to avoid bot detection
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,451 @@
|
||||
---
|
||||
title: Kubernetes Deployment
|
||||
subtitle: Deploy Skyvern at scale with Kubernetes manifests
|
||||
description: Deploy Skyvern on Kubernetes for production environments with horizontal scaling and high availability. Includes manifests for the API server, frontend, PostgreSQL, and ingress configuration.
|
||||
slug: developers/self-hosted/kubernetes
|
||||
keywords:
|
||||
- Kubernetes
|
||||
- Helm
|
||||
- manifests
|
||||
- horizontal scaling
|
||||
- high availability
|
||||
- ingress
|
||||
- PostgreSQL
|
||||
- production
|
||||
---
|
||||
|
||||
This guide walks through deploying Skyvern on Kubernetes for production environments. Use this when you need horizontal scaling, high availability, or integration with existing Kubernetes infrastructure.
|
||||
|
||||
<Warning>
|
||||
Do not expose this deployment to the public internet without adding authentication at the ingress layer.
|
||||
</Warning>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A running Kubernetes cluster (1.19+)
|
||||
- `kubectl` configured to access your cluster
|
||||
- An ingress controller (the manifests use Traefik, but any controller works)
|
||||
- An LLM API key (OpenAI, Anthropic, Azure, etc.)
|
||||
|
||||
## Architecture overview
|
||||
|
||||
The Kubernetes deployment creates three services:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Kubernetes Cluster
|
||||
Ingress[Ingress] --> FE[Frontend<br/>:8080]
|
||||
Ingress --> BE[Backend<br/>:8000]
|
||||
Ingress --> Art[Artifacts<br/>:9090]
|
||||
BE --> DB[(PostgreSQL<br/>:5432)]
|
||||
BE --> Browser[Browser<br/>embedded]
|
||||
FE --> Art
|
||||
end
|
||||
|
||||
BE --> LLM[LLM Provider]
|
||||
```
|
||||
|
||||
| Component | Service | Purpose |
|
||||
|-----------|---------|---------|
|
||||
| Backend | `skyvern-backend` | API server + embedded browser |
|
||||
| Frontend | `skyvern-frontend` | Web UI + artifact server |
|
||||
| PostgreSQL | `postgres` | Database for tasks, workflows, credentials |
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Skyvern-AI/skyvern.git
|
||||
cd skyvern/kubernetes-deployment
|
||||
```
|
||||
|
||||
### 2. Configure backend secrets
|
||||
|
||||
Edit `backend/backend-secrets.yaml` with your LLM provider credentials:
|
||||
|
||||
```yaml backend/backend-secrets.yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: skyvern-backend-env
|
||||
namespace: skyvern
|
||||
type: Opaque
|
||||
stringData:
|
||||
ENV: local
|
||||
|
||||
# LLM Configuration - set your provider
|
||||
ENABLE_OPENAI: "true"
|
||||
OPENAI_API_KEY: "sk-your-api-key-here"
|
||||
LLM_KEY: "OPENAI_GPT5_5"
|
||||
|
||||
# Database - points to the PostgreSQL service
|
||||
DATABASE_STRING: "postgresql+psycopg://skyvern:skyvern@postgres/skyvern"
|
||||
|
||||
# Browser settings
|
||||
BROWSER_TYPE: "chromium-headless"
|
||||
BROWSER_ACTION_TIMEOUT_MS: "5000"
|
||||
MAX_STEPS_PER_RUN: "10"
|
||||
|
||||
# Server
|
||||
PORT: "8000"
|
||||
LOG_LEVEL: "INFO"
|
||||
```
|
||||
|
||||
For other LLM providers, see [LLM Configuration](/developers/self-hosted/llm-configuration).
|
||||
|
||||
### 3. Configure frontend secrets
|
||||
|
||||
Edit `frontend/frontend-secrets.yaml`:
|
||||
|
||||
```yaml frontend/frontend-secrets.yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: skyvern-frontend-env
|
||||
namespace: skyvern
|
||||
type: Opaque
|
||||
stringData:
|
||||
VITE_API_BASE_URL: "http://skyvern.example.com/api/v1"
|
||||
VITE_WSS_BASE_URL: "ws://skyvern.example.com/api/v1"
|
||||
VITE_ARTIFACT_API_BASE_URL: "http://skyvern.example.com/artifacts"
|
||||
VITE_SKYVERN_API_KEY: "" # Leave empty for initial deploy
|
||||
```
|
||||
|
||||
Replace `skyvern.example.com` with your actual domain.
|
||||
|
||||
### 4. Configure ingress
|
||||
|
||||
Edit `ingress.yaml` with your domain and TLS settings:
|
||||
|
||||
```yaml ingress.yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: skyvern-ingress
|
||||
namespace: skyvern
|
||||
annotations:
|
||||
# Adjust for your ingress controller
|
||||
traefik.ingress.kubernetes.io/router.entrypoints: websecure
|
||||
spec:
|
||||
ingressClassName: traefik # Change to nginx, kong, etc.
|
||||
rules:
|
||||
- host: skyvern.example.com # Your domain
|
||||
http:
|
||||
paths:
|
||||
- path: /api
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: skyvern-backend
|
||||
port:
|
||||
number: 8000
|
||||
- path: /artifacts
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: skyvern-frontend
|
||||
port:
|
||||
number: 9090
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: skyvern-frontend
|
||||
port:
|
||||
number: 8080
|
||||
```
|
||||
|
||||
### 5. Deploy
|
||||
|
||||
Run the deployment script:
|
||||
|
||||
```bash
|
||||
chmod +x k8s-deploy.sh
|
||||
./k8s-deploy.sh
|
||||
```
|
||||
|
||||
This applies manifests in order:
|
||||
1. Namespace
|
||||
2. PostgreSQL (secrets, storage, deployment, service)
|
||||
3. Backend (secrets, deployment, service)
|
||||
4. Frontend (secrets, deployment, service)
|
||||
5. Ingress
|
||||
|
||||
### 6. Verify deployment
|
||||
|
||||
Check that all pods are running:
|
||||
|
||||
```bash
|
||||
kubectl get pods -n skyvern
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
postgres-xxx 1/1 Running 0 2m
|
||||
skyvern-backend-xxx 1/1 Running 0 1m
|
||||
skyvern-frontend-xxx 1/1 Running 0 30s
|
||||
```
|
||||
|
||||
The backend pod takes 1-2 minutes to become ready as it runs database migrations.
|
||||
|
||||
### 7. Get your API key
|
||||
|
||||
Wait for the backend pod to show `1/1` in the `READY` column of `kubectl get pods -n skyvern` before running this command. The API key file is generated during startup and won't exist until the pod is ready.
|
||||
|
||||
```bash
|
||||
kubectl exec -n skyvern deployment/skyvern-backend -- cat /app/.skyvern/credentials.toml
|
||||
```
|
||||
|
||||
Copy the `cred` value and update `frontend/frontend-secrets.yaml`:
|
||||
|
||||
```yaml
|
||||
VITE_SKYVERN_API_KEY: "eyJhbGciOiJIUzI1..."
|
||||
```
|
||||
|
||||
Reapply the frontend secrets and restart:
|
||||
|
||||
```bash
|
||||
kubectl apply -f frontend/frontend-secrets.yaml -n skyvern
|
||||
kubectl rollout restart deployment/skyvern-frontend -n skyvern
|
||||
```
|
||||
|
||||
### 8. Access the UI
|
||||
|
||||
Navigate to your configured domain (e.g., `https://skyvern.example.com`). You should see the Skyvern dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Manifest structure
|
||||
|
||||
```
|
||||
kubernetes-deployment/
|
||||
├── namespace.yaml # Creates 'skyvern' namespace
|
||||
├── k8s-deploy.sh # Deployment script
|
||||
├── ingress.yaml # Ingress configuration
|
||||
├── backend/
|
||||
│ ├── backend-secrets.yaml # Environment variables
|
||||
│ ├── backend-deployment.yaml # Pod spec
|
||||
│ └── backend-service.yaml # ClusterIP service
|
||||
├── frontend/
|
||||
│ ├── frontend-secrets.yaml # Environment variables
|
||||
│ ├── frontend-deployment.yaml # Pod spec
|
||||
│ └── frontend-service.yaml # ClusterIP service
|
||||
└── postgres/
|
||||
├── postgres-secrets.yaml # Database credentials
|
||||
├── postgres-storage.yaml # PersistentVolumeClaim
|
||||
├── postgres-deployment.yaml # Pod spec
|
||||
└── postgres-service.yaml # ClusterIP service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storage configuration
|
||||
|
||||
By default, the manifests use `hostPath` volumes. This works for single-node clusters but isn't suitable for multi-node production deployments.
|
||||
|
||||
### Using PersistentVolumeClaims
|
||||
|
||||
For production, replace `hostPath` with PVCs. Edit `backend/backend-deployment.yaml`:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- name: artifacts
|
||||
persistentVolumeClaim:
|
||||
claimName: skyvern-artifacts-pvc
|
||||
- name: videos
|
||||
persistentVolumeClaim:
|
||||
claimName: skyvern-videos-pvc
|
||||
```
|
||||
|
||||
Create the PVCs:
|
||||
|
||||
```yaml skyvern-storage.yaml
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: skyvern-artifacts-pvc
|
||||
namespace: skyvern
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 50Gi
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: skyvern-videos-pvc
|
||||
namespace: skyvern
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 100Gi
|
||||
```
|
||||
|
||||
### Using S3 or Azure Blob
|
||||
|
||||
For cloud storage, configure the backend environment variables instead of mounting volumes. See [Storage Configuration](/developers/self-hosted/storage).
|
||||
|
||||
---
|
||||
|
||||
## Scaling
|
||||
|
||||
### Horizontal scaling
|
||||
|
||||
To run multiple backend instances, increase the replica count:
|
||||
|
||||
```yaml backend/backend-deployment.yaml
|
||||
spec:
|
||||
replicas: 3 # Run 3 backend pods
|
||||
```
|
||||
|
||||
Each pod runs its own browser instance. Tasks are distributed across pods.
|
||||
|
||||
<Note>
|
||||
When scaling horizontally, ensure your storage backend supports concurrent access (S3, Azure Blob, or ReadWriteMany PVCs). Local storage with ReadWriteOnce PVCs won't work across multiple pods.
|
||||
</Note>
|
||||
|
||||
### Resource limits
|
||||
|
||||
Add resource limits to prevent pods from consuming excessive resources:
|
||||
|
||||
```yaml
|
||||
containers:
|
||||
- name: skyvern-backend
|
||||
resources:
|
||||
requests:
|
||||
memory: "2Gi"
|
||||
cpu: "500m"
|
||||
limits:
|
||||
memory: "4Gi"
|
||||
cpu: "2000m"
|
||||
```
|
||||
|
||||
Browser instances need significant memory. Start with 2GB minimum per pod.
|
||||
|
||||
---
|
||||
|
||||
## TLS configuration
|
||||
|
||||
To enable HTTPS, uncomment the TLS section in `ingress.yaml`:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- skyvern.example.com
|
||||
secretName: skyvern-tls-secret
|
||||
```
|
||||
|
||||
Create the TLS secret:
|
||||
|
||||
```bash
|
||||
kubectl create secret tls skyvern-tls-secret \
|
||||
--cert=path/to/tls.crt \
|
||||
--key=path/to/tls.key \
|
||||
-n skyvern
|
||||
```
|
||||
|
||||
Or use cert-manager for automatic certificate management.
|
||||
|
||||
Update frontend secrets to use `https` and `wss`:
|
||||
|
||||
```yaml
|
||||
VITE_API_BASE_URL: "https://skyvern.example.com/api/v1"
|
||||
VITE_WSS_BASE_URL: "wss://skyvern.example.com/api/v1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using an external database
|
||||
|
||||
For production, consider using a managed PostgreSQL service (RDS, Cloud SQL, Azure Database).
|
||||
|
||||
1. Remove the `postgres/` manifests from the deployment
|
||||
2. Update `backend/backend-secrets.yaml`:
|
||||
|
||||
```yaml
|
||||
DATABASE_STRING: "postgresql+psycopg://user:password@your-db-host:5432/skyvern"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pods stuck in Pending
|
||||
|
||||
Check for resource constraints:
|
||||
|
||||
```bash
|
||||
kubectl describe pod -n skyvern <pod-name>
|
||||
```
|
||||
|
||||
Common causes:
|
||||
- Insufficient node resources
|
||||
- PersistentVolume not available
|
||||
- Image pull errors
|
||||
|
||||
### Backend crashes on startup
|
||||
|
||||
Check the logs:
|
||||
|
||||
```bash
|
||||
kubectl logs -n skyvern deployment/skyvern-backend
|
||||
```
|
||||
|
||||
Common causes:
|
||||
- Invalid LLM API key
|
||||
- Database connection failed
|
||||
- Missing environment variables
|
||||
|
||||
### Frontend shows "Unauthorized"
|
||||
|
||||
The API key in frontend secrets doesn't match the generated key. Re-copy it from the backend pod.
|
||||
|
||||
### Ingress not routing correctly
|
||||
|
||||
Verify your ingress controller is running and the ingress resource is configured:
|
||||
|
||||
```bash
|
||||
kubectl get ingress -n skyvern
|
||||
kubectl describe ingress skyvern-ingress -n skyvern
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cleanup
|
||||
|
||||
To remove the entire deployment:
|
||||
|
||||
```bash
|
||||
kubectl delete namespace skyvern
|
||||
```
|
||||
|
||||
This removes all resources in the `skyvern` namespace.
|
||||
|
||||
To clean up host storage (if using hostPath):
|
||||
|
||||
```bash
|
||||
rm -rf /data/artifacts /data/videos /data/har /data/log /app/.skyvern
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
|
||||
Configure S3 or Azure Blob for artifact storage
|
||||
</Card>
|
||||
<Card title="LLM Configuration" icon="microchip" href="/developers/self-hosted/llm-configuration">
|
||||
Configure additional LLM providers
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,616 @@
|
||||
---
|
||||
title: LLM Configuration
|
||||
subtitle: Connect your preferred language model provider
|
||||
description: Configure LLM providers for self-hosted Skyvern including OpenAI, Anthropic, Azure OpenAI, Google Gemini, AWS Bedrock, Ollama, and OpenAI-compatible endpoints via LiteLLM.
|
||||
slug: developers/self-hosted/llm-configuration
|
||||
keywords:
|
||||
- OpenAI
|
||||
- Anthropic
|
||||
- Azure OpenAI
|
||||
- Google Gemini
|
||||
- AWS Bedrock
|
||||
- Ollama
|
||||
- LiteLLM
|
||||
- LLM_KEY
|
||||
- SECONDARY_LLM_KEY
|
||||
---
|
||||
|
||||
Skyvern uses LLMs to analyze screenshots and decide what actions to take. You'll need to configure at least one LLM provider before running tasks.
|
||||
|
||||
## How Skyvern uses LLMs
|
||||
|
||||
Skyvern makes multiple LLM calls per task step:
|
||||
1. **Screenshot analysis**: Identify interactive elements on the page
|
||||
2. **Action planning**: Decide what to click, type, or extract
|
||||
3. **Result extraction**: Parse data from the page into structured output
|
||||
|
||||
A task that runs for 10 steps makes roughly 30+ LLM calls. Choose your provider and model tier with this in mind.
|
||||
|
||||
For most deployments, configure a single provider using `LLM_KEY`. Skyvern also supports a `SECONDARY_LLM_KEY` for lighter tasks to reduce costs.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Recommendations
|
||||
|
||||
**Best models for production (2026):**
|
||||
|
||||
| Provider | Primary Model | Secondary Model | Notes |
|
||||
|----------|--------------|-----------------|-------|
|
||||
| **Anthropic** | `ANTHROPIC_CLAUDE4.7_OPUS` | `ANTHROPIC_CLAUDE4.6_SONNET` | Most capable |
|
||||
| **OpenAI** | `OPENAI_GPT5_5` | `OPENAI_GPT5_4` | Latest |
|
||||
| **Google** | `GEMINI_3_PRO` | `GEMINI_3.0_FLASH` | Latest |
|
||||
| **AWS Bedrock** | `BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE` | `BEDROCK_ANTHROPIC_CLAUDE4.6_SONNET_INFERENCE_PROFILE` | Latest Claude |
|
||||
|
||||
---
|
||||
|
||||
## OpenAI
|
||||
|
||||
The most common choice. Requires an API key from [platform.openai.com](https://platform.openai.com/).
|
||||
|
||||
```bash .env
|
||||
ENABLE_OPENAI=true
|
||||
OPENAI_API_KEY=sk-...
|
||||
LLM_KEY=OPENAI_GPT5_5
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **GPT-5.5** | |
|
||||
| `OPENAI_GPT5_5` | Latest flagship, recommended for complex tasks |
|
||||
| **GPT-5 Series** | |
|
||||
| `OPENAI_GPT5_4` | |
|
||||
| `OPENAI_GPT5` | |
|
||||
| `OPENAI_GPT5_MINI` | |
|
||||
| `OPENAI_GPT5_MINI_FLEX` | Flex service tier, 15min timeout |
|
||||
| `OPENAI_GPT5_NANO` | |
|
||||
| `OPENAI_GPT5_1` | |
|
||||
| `OPENAI_GPT5_2` | |
|
||||
| **GPT-4 Series** | |
|
||||
| `OPENAI_GPT4O` | |
|
||||
| `OPENAI_GPT4O_MINI` | |
|
||||
| `OPENAI_GPT4_1` | |
|
||||
| `OPENAI_GPT4_1_MINI` | |
|
||||
| `OPENAI_GPT4_1_NANO` | |
|
||||
| `OPENAI_GPT4_5` | |
|
||||
| `OPENAI_GPT4_TURBO` | Legacy |
|
||||
| `OPENAI_GPT4V` | Legacy alias |
|
||||
| **O-Series (Reasoning)** | |
|
||||
| `OPENAI_O4_MINI` | Vision support |
|
||||
| `OPENAI_O3` | Vision support |
|
||||
| `OPENAI_O3_MINI` | No vision |
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash .env
|
||||
# Use a custom API endpoint (for proxies or compatible services)
|
||||
OPENAI_API_BASE=https://your-proxy.com/v1
|
||||
|
||||
# Specify organization ID
|
||||
OPENAI_ORGANIZATION=org-...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anthropic
|
||||
|
||||
Claude models from [anthropic.com](https://www.anthropic.com/).
|
||||
|
||||
```bash .env
|
||||
ENABLE_ANTHROPIC=true
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **Claude 4.7** | |
|
||||
| `ANTHROPIC_CLAUDE4.7_OPUS` | Latest, most capable |
|
||||
| **Claude 4.6** | |
|
||||
| `ANTHROPIC_CLAUDE4.6_OPUS` | |
|
||||
| `ANTHROPIC_CLAUDE4.6_SONNET` | Recommended for secondary use |
|
||||
| **Claude 4.5** | |
|
||||
| `ANTHROPIC_CLAUDE4.5_OPUS` | |
|
||||
| `ANTHROPIC_CLAUDE4.5_SONNET` | |
|
||||
| `ANTHROPIC_CLAUDE4.5_HAIKU` | Fastest |
|
||||
| **Claude 4** | |
|
||||
| `ANTHROPIC_CLAUDE4_OPUS` | |
|
||||
| `ANTHROPIC_CLAUDE4_SONNET` | |
|
||||
| **Claude 3.7** | |
|
||||
| `ANTHROPIC_CLAUDE3.7_SONNET` | |
|
||||
| **Claude 3.5** | |
|
||||
| `ANTHROPIC_CLAUDE3.5_SONNET` | |
|
||||
| `ANTHROPIC_CLAUDE3.5_HAIKU` | |
|
||||
| **Claude 3 (Legacy)** | |
|
||||
| `ANTHROPIC_CLAUDE3_OPUS` | |
|
||||
| `ANTHROPIC_CLAUDE3_SONNET` | |
|
||||
| `ANTHROPIC_CLAUDE3_HAIKU` | |
|
||||
|
||||
---
|
||||
|
||||
## Azure OpenAI
|
||||
|
||||
Microsoft-hosted OpenAI models. Requires an Azure subscription with OpenAI service provisioned.
|
||||
|
||||
```bash .env
|
||||
ENABLE_AZURE=true
|
||||
LLM_KEY=AZURE_OPENAI
|
||||
AZURE_DEPLOYMENT=your-deployment-name
|
||||
AZURE_API_KEY=your-azure-api-key
|
||||
AZURE_API_BASE=https://your-resource.openai.azure.com/
|
||||
AZURE_API_VERSION=2024-08-01-preview
|
||||
```
|
||||
|
||||
### Setup steps
|
||||
|
||||
1. Create an Azure OpenAI resource in the [Azure Portal](https://portal.azure.com)
|
||||
2. Open the Azure AI Foundry portal from your resource's overview page
|
||||
3. Go to **Shared Resources** → **Deployments**
|
||||
4. Click **Deploy Model** → **Deploy Base Model** → select GPT-4o or GPT-4
|
||||
5. Note the **Deployment Name**. Use this for `AZURE_DEPLOYMENT`
|
||||
6. Copy your API key and endpoint from the Azure Portal
|
||||
|
||||
<Note>
|
||||
The `AZURE_DEPLOYMENT` is the name you chose when deploying the model, not the model name itself.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Google Gemini
|
||||
|
||||
Skyvern supports Gemini through two paths: the **Gemini API** (simpler, uses an API key) and **Vertex AI** (enterprise, uses a GCP service account).
|
||||
|
||||
### Gemini API
|
||||
|
||||
The quickest way to use Gemini. Get an API key from [Google AI Studio](https://aistudio.google.com/).
|
||||
|
||||
```bash .env
|
||||
ENABLE_GEMINI=true
|
||||
GEMINI_API_KEY=your-gemini-api-key
|
||||
LLM_KEY=GEMINI_2.5_PRO
|
||||
```
|
||||
|
||||
#### Available Gemini API models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **Gemini 3** | |
|
||||
| `GEMINI_3_PRO` | Recommended for primary use |
|
||||
| `GEMINI_3.0_FLASH` | Recommended for secondary use |
|
||||
| `GEMINI_3.1_FLASH_LITE` | Fastest, most cost-efficient |
|
||||
| **Gemini 2.5** | |
|
||||
| `GEMINI_2.5_PRO` | |
|
||||
| `GEMINI_2.5_PRO_PREVIEW` | |
|
||||
| `GEMINI_2.5_PRO_EXP_03_25` | Experimental |
|
||||
| `GEMINI_2.5_FLASH` | |
|
||||
| `GEMINI_2.5_FLASH_PREVIEW` | |
|
||||
| **Gemini 2.0** | |
|
||||
| `GEMINI_FLASH_2_0` | |
|
||||
| `GEMINI_FLASH_2_0_LITE` | |
|
||||
| **Gemini 1.5 Legacy** | |
|
||||
| `GEMINI_PRO` | |
|
||||
| `GEMINI_FLASH` | |
|
||||
|
||||
### Vertex AI
|
||||
|
||||
For enterprise deployments through [Vertex AI](https://cloud.google.com/vertex-ai). Requires a GCP project with Vertex AI enabled.
|
||||
|
||||
```bash .env
|
||||
ENABLE_VERTEX_AI=true
|
||||
LLM_KEY=VERTEX_GEMINI_3_PRO
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
||||
GCP_PROJECT_ID=your-gcp-project-id
|
||||
VERTEX_LOCATION=us-central1
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you're migrating from an older Skyvern version, `VERTEX_LOCATION` replaces the previous `GCP_REGION` variable. Update your `.env` accordingly.
|
||||
</Note>
|
||||
|
||||
**Vertex AI setup steps:**
|
||||
|
||||
1. Create a [GCP project](https://console.cloud.google.com/) with billing enabled
|
||||
2. Enable the **Vertex AI API** in your project
|
||||
3. Create a service account with the **Vertex AI User** role
|
||||
4. Download the service account JSON key file
|
||||
5. Set `GOOGLE_APPLICATION_CREDENTIALS` to the path of that file
|
||||
|
||||
<Note>
|
||||
For global endpoint access, set `VERTEX_LOCATION=global` and ensure `VERTEX_PROJECT_ID` is set. Not all models support the global endpoint.
|
||||
</Note>
|
||||
|
||||
#### Available Vertex AI models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **Gemini 3** | |
|
||||
| `VERTEX_GEMINI_3_PRO` | Recommended for primary use |
|
||||
| `VERTEX_GEMINI_3.0_FLASH` | Recommended for secondary use |
|
||||
| `VERTEX_GEMINI_3.1_FLASH_LITE` | Fastest, most cost-efficient |
|
||||
| **Gemini 2.5** | |
|
||||
| `VERTEX_GEMINI_2.5_PRO` | |
|
||||
| `VERTEX_GEMINI_2.5_PRO_PREVIEW` | |
|
||||
| `VERTEX_GEMINI_2.5_FLASH` | |
|
||||
| `VERTEX_GEMINI_2.5_FLASH_LITE` | |
|
||||
| `VERTEX_GEMINI_2.5_FLASH_PREVIEW` | |
|
||||
| **Gemini 2.0** | |
|
||||
| `VERTEX_GEMINI_FLASH_2_0` | |
|
||||
| **Gemini 1.5 Legacy** | |
|
||||
| `VERTEX_GEMINI_PRO` | |
|
||||
| `VERTEX_GEMINI_FLASH` | |
|
||||
|
||||
---
|
||||
|
||||
## Amazon Bedrock
|
||||
|
||||
Run Anthropic Claude through your AWS account.
|
||||
|
||||
```bash .env
|
||||
ENABLE_BEDROCK=true
|
||||
LLM_KEY=BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE
|
||||
AWS_REGION=us-west-2
|
||||
AWS_ACCESS_KEY_ID=AKIA...
|
||||
AWS_SECRET_ACCESS_KEY=...
|
||||
```
|
||||
|
||||
### Setup steps
|
||||
|
||||
1. Create an IAM user with `AmazonBedrockFullAccess` policy
|
||||
2. Generate access keys for the IAM user
|
||||
3. In the [Bedrock console](https://console.aws.amazon.com/bedrock/), go to **Model Access**
|
||||
4. Enable access to Claude Opus 4.7
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **Amazon Nova (AWS Native)** | |
|
||||
| `BEDROCK_AMAZON_NOVA_PRO` | |
|
||||
| `BEDROCK_AMAZON_NOVA_LITE` | |
|
||||
| **Claude 4.7** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE` | Cross-region, latest |
|
||||
| **Claude 4.6** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4.6_OPUS_INFERENCE_PROFILE` | Cross-region |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4.6_SONNET_INFERENCE_PROFILE` | Cross-region |
|
||||
| **Claude 4.5** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4.5_OPUS_INFERENCE_PROFILE` | Cross-region |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4.5_SONNET_INFERENCE_PROFILE` | Cross-region |
|
||||
| **Claude 4** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4_OPUS_INFERENCE_PROFILE` | Cross-region |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE4_SONNET_INFERENCE_PROFILE` | Cross-region |
|
||||
| **Claude 3.7** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3.7_SONNET_INFERENCE_PROFILE` | Cross-region |
|
||||
| **Claude 3.5** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET` | v2 |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET_V1` | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET_INFERENCE_PROFILE` | Cross-region |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3.5_HAIKU` | |
|
||||
| **Claude 3 (Legacy)** | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3_OPUS` | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3_SONNET` | |
|
||||
| `BEDROCK_ANTHROPIC_CLAUDE3_HAIKU` | |
|
||||
|
||||
<Note>
|
||||
Bedrock inference profile keys (`*_INFERENCE_PROFILE`) use cross-region inference and require `AWS_REGION` only. No access keys needed if running on an IAM-authenticated instance.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## MiniMax
|
||||
|
||||
[MiniMax](https://www.minimax.io/) models with vision support.
|
||||
|
||||
```bash .env
|
||||
ENABLE_MINIMAX=true
|
||||
MINIMAX_API_KEY=your-minimax-api-key
|
||||
LLM_KEY=MINIMAX_M2_5
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| `MINIMAX_M2_5` | |
|
||||
| `MINIMAX_M2_5_HIGHSPEED` | Faster variant |
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash .env
|
||||
# Use a custom API endpoint
|
||||
MINIMAX_API_BASE=https://api.minimax.io/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VolcEngine (ByteDance Doubao)
|
||||
|
||||
[VolcEngine](https://www.volcengine.com/) provides access to ByteDance's Doubao models with vision support.
|
||||
|
||||
```bash .env
|
||||
ENABLE_VOLCENGINE=true
|
||||
VOLCENGINE_API_KEY=your-volcengine-api-key
|
||||
LLM_KEY=VOLCENGINE_DOUBAO_SEED_1_6
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| `VOLCENGINE_DOUBAO_SEED_1_6` | Recommended for general use |
|
||||
| `VOLCENGINE_DOUBAO_SEED_1_6_FLASH` | Faster variant |
|
||||
| `VOLCENGINE_DOUBAO_1_5_THINKING_VISION_PRO` | Reasoning model |
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash .env
|
||||
# Use a custom API endpoint
|
||||
VOLCENGINE_API_BASE=https://ark.cn-beijing.volces.com/api/v3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Novita
|
||||
|
||||
[Novita AI](https://novita.ai/) provides access to DeepSeek, Llama, and other open-source models.
|
||||
|
||||
```bash .env
|
||||
ENABLE_NOVITA=true
|
||||
NOVITA_API_KEY=your-novita-api-key
|
||||
LLM_KEY=NOVITA_LLAMA_3_2_11B_VISION
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| **DeepSeek** | |
|
||||
| `NOVITA_DEEPSEEK_R1` | Reasoning model |
|
||||
| `NOVITA_DEEPSEEK_V3` | |
|
||||
| **Llama 3.3** | |
|
||||
| `NOVITA_LLAMA_3_3_70B` | |
|
||||
| **Llama 3.2** | |
|
||||
| `NOVITA_LLAMA_3_2_11B_VISION` | Vision support |
|
||||
| `NOVITA_LLAMA_3_2_3B` | |
|
||||
| `NOVITA_LLAMA_3_2_1B` | |
|
||||
| **Llama 3.1** | |
|
||||
| `NOVITA_LLAMA_3_1_405B` | |
|
||||
| `NOVITA_LLAMA_3_1_70B` | |
|
||||
| `NOVITA_LLAMA_3_1_8B` | |
|
||||
| **Llama 3** | |
|
||||
| `NOVITA_LLAMA_3_70B` | |
|
||||
| `NOVITA_LLAMA_3_8B` | |
|
||||
|
||||
---
|
||||
|
||||
## Moonshot
|
||||
|
||||
[Moonshot AI](https://www.moonshot.cn/) provides the Kimi series models with long context support.
|
||||
|
||||
```bash .env
|
||||
ENABLE_MOONSHOT=true
|
||||
MOONSHOT_API_KEY=your-moonshot-api-key
|
||||
LLM_KEY=MOONSHOT_KIMI_K2
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| `MOONSHOT_KIMI_K2` | |
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash .env
|
||||
# Use a custom API endpoint
|
||||
MOONSHOT_API_BASE=https://api.moonshot.cn/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inception
|
||||
|
||||
[Inception AI](https://inception.ai/) provides the Mercury series models.
|
||||
|
||||
```bash .env
|
||||
ENABLE_INCEPTION=true
|
||||
INCEPTION_API_KEY=your-inception-api-key
|
||||
LLM_KEY=INCEPTION_MERCURY_2
|
||||
```
|
||||
|
||||
### Available models
|
||||
|
||||
| LLM_KEY | Notes |
|
||||
|---------|-------|
|
||||
| `INCEPTION_MERCURY_2` | |
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash .env
|
||||
# Use a custom API endpoint
|
||||
INCEPTION_API_BASE=https://api.inception.ai/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ollama (Local Models)
|
||||
|
||||
Run open-source models locally with [Ollama](https://ollama.ai/). No API costs, but requires sufficient local compute.
|
||||
|
||||
```bash .env
|
||||
ENABLE_OLLAMA=true
|
||||
LLM_KEY=OLLAMA
|
||||
OLLAMA_MODEL=gemma4
|
||||
OLLAMA_SERVER_URL=http://host.docker.internal:11434
|
||||
OLLAMA_SUPPORTS_VISION=false
|
||||
```
|
||||
|
||||
### Setup steps
|
||||
|
||||
1. [Install Ollama](https://ollama.ai/download)
|
||||
2. Pull a model: `ollama pull gemma4`
|
||||
3. Start Ollama: `ollama serve`
|
||||
4. Configure Skyvern to connect
|
||||
|
||||
<Warning>
|
||||
Most Ollama models don't support vision. Set `OLLAMA_SUPPORTS_VISION=false`. Without vision, Skyvern relies on DOM analysis instead of screenshot analysis, which may reduce accuracy on complex pages.
|
||||
</Warning>
|
||||
|
||||
### Docker networking
|
||||
|
||||
When running Skyvern in Docker and Ollama on the host:
|
||||
|
||||
| Host OS | OLLAMA_SERVER_URL |
|
||||
|---------|-------------------|
|
||||
| macOS/Windows | `http://host.docker.internal:11434` |
|
||||
| Linux | `http://172.17.0.1:11434` (Docker bridge IP) |
|
||||
|
||||
---
|
||||
|
||||
## OpenAI-Compatible Endpoints
|
||||
|
||||
Connect to any service that implements the OpenAI API format, including LiteLLM, LocalAI, vLLM, and text-generation-inference.
|
||||
|
||||
```bash .env
|
||||
ENABLE_OPENAI_COMPATIBLE=true
|
||||
OPENAI_COMPATIBLE_MODEL_NAME=gemma4
|
||||
OPENAI_COMPATIBLE_API_KEY=sk-test
|
||||
OPENAI_COMPATIBLE_API_BASE=http://localhost:4000/v1
|
||||
LLM_KEY=OPENAI_COMPATIBLE
|
||||
```
|
||||
|
||||
This is useful for:
|
||||
- Running local models with a unified API
|
||||
- Using LiteLLM as a proxy to switch between providers
|
||||
- Connecting to self-hosted inference servers
|
||||
|
||||
---
|
||||
|
||||
## OpenRouter
|
||||
|
||||
Access multiple models through a single API at [openrouter.ai](https://openrouter.ai/).
|
||||
|
||||
```bash .env
|
||||
ENABLE_OPENROUTER=true
|
||||
LLM_KEY=OPENROUTER
|
||||
OPENROUTER_API_KEY=sk-or-...
|
||||
OPENROUTER_MODEL=mistralai/mistral-small-3.1-24b-instruct
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Groq
|
||||
|
||||
Inference on open-source models at [groq.com](https://groq.com/).
|
||||
|
||||
```bash .env
|
||||
ENABLE_GROQ=true
|
||||
LLM_KEY=GROQ
|
||||
GROQ_API_KEY=gsk_...
|
||||
GROQ_MODEL=llama-3.1-8b-instant
|
||||
```
|
||||
|
||||
<Note>
|
||||
Groq specializes in fast inference for open-source models. Response times are typically much faster than other providers, but model selection is limited.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Using multiple models
|
||||
|
||||
### Primary and secondary models
|
||||
|
||||
Configure a cheaper model for lightweight operations:
|
||||
|
||||
```bash .env
|
||||
# Main model for complex decisions
|
||||
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
|
||||
# or: OPENAI_GPT5_5
|
||||
# or: GEMINI_3_PRO
|
||||
|
||||
# Faster model for simple tasks like dropdown selection
|
||||
SECONDARY_LLM_KEY=ANTHROPIC_CLAUDE4.6_SONNET
|
||||
# or: OPENAI_GPT5_4
|
||||
# or: GEMINI_3.0_FLASH
|
||||
```
|
||||
|
||||
<Tip>
|
||||
**Recommended primary models (latest):**
|
||||
- **Anthropic Claude 4.7 Opus** (`ANTHROPIC_CLAUDE4.7_OPUS`) - Most capable
|
||||
- **OpenAI GPT-5.5** (`OPENAI_GPT5_5`) - Latest
|
||||
- **Google Gemini 3 Pro** (`GEMINI_3_PRO`) - Latest
|
||||
|
||||
**Recommended secondary models (latest):**
|
||||
- **Claude 4.6 Sonnet** (`ANTHROPIC_CLAUDE4.6_SONNET`) - Balanced
|
||||
- **GPT-5.4** (`OPENAI_GPT5_4`) - Fast reasoning
|
||||
- **Gemini 3.0 Flash** (`GEMINI_3.0_FLASH`) - Faster Gemini 3
|
||||
</Tip>
|
||||
|
||||
### Task-specific models
|
||||
|
||||
For fine-grained control, you can override models for specific operations:
|
||||
|
||||
```bash .env
|
||||
# Model for data extraction from pages (defaults to LLM_KEY if not set)
|
||||
EXTRACTION_LLM_KEY=ANTHROPIC_CLAUDE4.5_SONNET
|
||||
|
||||
# Model for generating code/scripts in code blocks (defaults to LLM_KEY if not set)
|
||||
SCRIPT_GENERATION_LLM_KEY=OPENAI_GPT5
|
||||
```
|
||||
|
||||
Most deployments don't need task-specific models. Start with `LLM_KEY` and `SECONDARY_LLM_KEY`.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "To enable svg shape conversion, please set the Secondary LLM key"
|
||||
|
||||
Some operations require a secondary model. Set `SECONDARY_LLM_KEY` in your environment:
|
||||
|
||||
```bash .env
|
||||
SECONDARY_LLM_KEY=OPENAI_GPT5_4
|
||||
```
|
||||
|
||||
### "Context window exceeded"
|
||||
|
||||
The page content is too large for the model's context window. Options:
|
||||
- Use a model with larger context support (GPT-5.5, Gemini 2.5 Pro, or Claude 4.7 Opus)
|
||||
- Simplify your prompt to require less page analysis
|
||||
- Start from a more specific URL with less content
|
||||
|
||||
### "LLM caller not found"
|
||||
|
||||
The configured `LLM_KEY` doesn't match any enabled provider. Verify:
|
||||
1. The provider is enabled (`ENABLE_OPENAI=true`, etc.)
|
||||
2. The `LLM_KEY` value matches a supported model name exactly
|
||||
3. Model names are case-sensitive: `OPENAI_GPT5_5` not `openai_gpt5_5`
|
||||
|
||||
### Container logs show authentication errors
|
||||
|
||||
Check your API key configuration:
|
||||
- Ensure the key is set correctly without extra whitespace
|
||||
- Verify the key hasn't expired or been revoked
|
||||
- For Azure, ensure `AZURE_API_BASE` includes the full URL with `https://`
|
||||
|
||||
### Slow response times
|
||||
|
||||
LLM calls typically take 2-10 seconds. Longer times may indicate:
|
||||
- Network latency to the provider
|
||||
- Rate limiting (the provider may be throttling requests)
|
||||
- For Ollama, insufficient local compute resources
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Browser Configuration" icon="window" href="/developers/self-hosted/browser">
|
||||
Configure browser modes, locales, and display settings
|
||||
</Card>
|
||||
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
|
||||
Return to the main Docker setup guide
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Self-Hosted Overview
|
||||
subtitle: Run Skyvern on your own infrastructure
|
||||
description: Deploy Skyvern on your own infrastructure with Docker or Kubernetes. Configure LLM providers, browsers, proxies, and storage.
|
||||
slug: developers/self-hosted/overview
|
||||
keywords:
|
||||
- self-hosted
|
||||
- on-premise
|
||||
- infrastructure
|
||||
- deployment
|
||||
- architecture
|
||||
- components
|
||||
- requirements
|
||||
---
|
||||
|
||||
Self-hosted Skyvern runs entirely on your infrastructure: your servers, your browsers, your LLM API keys. This guide helps you decide if self-hosting fits your needs and which deployment method to choose.
|
||||
|
||||
## Architecture
|
||||
|
||||
Self-hosted Skyvern has four components running on your infrastructure:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Your Infrastructure
|
||||
API[Skyvern API Server<br/>+ Embedded Browser]
|
||||
UI[Skyvern Web UI]
|
||||
DB[(PostgreSQL)]
|
||||
end
|
||||
|
||||
LLM[LLM Provider]
|
||||
Sites[Target Websites]
|
||||
|
||||
UI <--> API
|
||||
API <--> DB
|
||||
API <--> LLM
|
||||
API <--> Sites
|
||||
```
|
||||
|
||||
| Component | Role |
|
||||
|-----------|------|
|
||||
| **Skyvern API Server** | Orchestrates tasks, processes LLM responses, stores results. Includes an embedded Playwright-managed Chromium browser that executes web automation. |
|
||||
| **Skyvern Web UI** | Browser-based dashboard for building workflows, running tasks, viewing recordings, and managing credentials. Docker Compose starts it alongside the API server. |
|
||||
| **PostgreSQL** | Stores task history, workflows, credentials, and organization data |
|
||||
| **LLM Provider** | Analyzes screenshots and determines actions. You provide the API key (OpenAI, Anthropic, Azure OpenAI, Google Vertex AI, Amazon Bedrock, Groq, OpenRouter, or local via Ollama) |
|
||||
|
||||
### How a task executes
|
||||
|
||||
Skyvern runs a perception-action loop for each task step:
|
||||
|
||||
1. **Screenshot**: The browser captures the current page state
|
||||
2. **Analyze**: The screenshot is sent to your LLM, which identifies interactive elements and decides the next action
|
||||
3. **Execute**: Skyvern performs the action in the browser (click, type, scroll, extract data)
|
||||
4. **Repeat**: Steps 1-3 loop until the task goal is met or the step limit (`MAX_STEPS_PER_RUN`) is reached
|
||||
|
||||
This loop is why LLM choice and browser configuration are the two most impactful self-hosting decisions. They affect every task step.
|
||||
|
||||
## What changes from Cloud
|
||||
|
||||
| You gain | You manage |
|
||||
|----------|------------|
|
||||
| Full data control: browser sessions and results stay on your network | Infrastructure: servers, scaling, uptime |
|
||||
| Any LLM provider, including local models via Ollama | LLM API costs: pay your provider directly |
|
||||
| No per-task pricing | Proxies: bring your own provider |
|
||||
| Full access to browser configuration and extensions | Software updates: pull new Docker images manually |
|
||||
| Deploy in air-gapped or restricted networks | Database backups and maintenance |
|
||||
|
||||
<Note>
|
||||
The most significant operational difference is **proxies**. Skyvern Cloud routes browser traffic through managed residential proxies to avoid bot detection. Self-hosted deployments need you to configure your own proxy provider.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before deploying, ensure you have:
|
||||
|
||||
<Steps>
|
||||
<Step title="Docker and Docker Compose">
|
||||
Required for containerized deployment. [Install Docker](https://docs.docker.com/get-docker/)
|
||||
</Step>
|
||||
<Step title="4GB+ RAM">
|
||||
Browser instances are memory-intensive. Production deployments benefit from 8GB+.
|
||||
</Step>
|
||||
<Step title="LLM API key">
|
||||
From OpenAI, Anthropic, Azure OpenAI, Google Gemini, or AWS Bedrock. Alternatively, run local models with Ollama.
|
||||
</Step>
|
||||
<Step title="Proxy provider (recommended)">
|
||||
For automating external websites at scale. Not required for internal tools or development.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
PostgreSQL 14+ is included in the Docker Compose setup. If you prefer an external database, configure `DATABASE_STRING` to point to your own instance.
|
||||
|
||||
For local server commands from PyPI, install the server extra: `pip install "skyvern[server]"`. The lightweight `pip install skyvern` package is for Skyvern Cloud / remote API SDK usage and does not include the local server stack. Guided quickstart and migrations currently require Docker Compose or a source checkout.
|
||||
|
||||
For a full self-hosted deployment with the web UI, use Docker Compose. The Compose stack starts the API server, browser runtime, Postgres, and the Skyvern web UI together.
|
||||
|
||||
For the source-checkout `pip install ".[server]"` path (Option A in the README), the default is a SQLite database at `~/.skyvern/data.db` — zero-config for local dev. To opt into Postgres for that path, run `skyvern quickstart --database-string=postgresql+psycopg://user:pass@host:5432/dbname`.
|
||||
|
||||
## Choose your deployment method
|
||||
|
||||
| Method | Best for |
|
||||
|--------|----------|
|
||||
| **Docker Compose** | Getting started, small teams, single-server deployments |
|
||||
| **Kubernetes** | Production at scale, teams with existing K8s infrastructure, high availability requirements |
|
||||
|
||||
Most teams start with Docker Compose. It's the fastest path to a working deployment. Move to Kubernetes when you need horizontal scaling or want to integrate with existing orchestration infrastructure.
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
|
||||
Get Skyvern running in 10 minutes with Docker Compose
|
||||
</Card>
|
||||
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
|
||||
Deploy to production with Kubernetes manifests
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,245 @@
|
||||
---
|
||||
title: Proxy Setup
|
||||
subtitle: Configure proxies to avoid bot detection
|
||||
description: Configure residential, ISP, or datacenter proxies for self-hosted Skyvern deployments to avoid bot detection, bypass geo-restrictions, and prevent rate limiting on target websites.
|
||||
slug: developers/self-hosted/proxy
|
||||
keywords:
|
||||
- residential proxy
|
||||
- ISP proxy
|
||||
- datacenter proxy
|
||||
- rate limiting
|
||||
- geo-restriction
|
||||
- PROXY_URL
|
||||
- configuration
|
||||
---
|
||||
|
||||
Many websites block requests from datacenter IPs or detect automated browser patterns. Skyvern Cloud includes managed residential proxies that handle this automatically. Self-hosted deployments require you to configure your own proxy provider.
|
||||
|
||||
## Why you need proxies
|
||||
|
||||
Without proxies, your browser automation traffic originates from your server's IP address. This causes issues when:
|
||||
|
||||
- **Target sites block datacenter IPs**: Many sites automatically block traffic from known hosting providers (AWS, GCP, Azure)
|
||||
- **Rate limiting**: Repeated requests from one IP trigger rate limits
|
||||
- **Geo-restrictions**: Sites serve different content based on location
|
||||
- **Bot detection**: Some sites fingerprint datacenter traffic patterns
|
||||
|
||||
<Note>
|
||||
If you're automating internal tools or sites that don't have bot detection, you may not need proxies at all. Test without proxies first.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Proxy types
|
||||
|
||||
### Residential proxies
|
||||
|
||||
Traffic appears to come from real home internet connections. Most expensive but least likely to be blocked. Recommended for browser automation. Start here unless cost is a primary concern.
|
||||
|
||||
**Providers:**
|
||||
- [Bright Data](https://brightdata.com/)
|
||||
- [Oxylabs](https://oxylabs.io/)
|
||||
- [Smartproxy](https://smartproxy.com/)
|
||||
- [IPRoyal](https://iproyal.com/)
|
||||
|
||||
### ISP proxies
|
||||
|
||||
Static IPs from internet service providers. Good balance between cost and detection avoidance.
|
||||
|
||||
### Datacenter proxies
|
||||
|
||||
IPs from cloud providers. Cheapest but most likely to be blocked.
|
||||
|
||||
### Rotating vs. static
|
||||
|
||||
See [Rotating proxies vs. sticky sessions](#rotating-proxies-vs-sticky-sessions) for guidance on which to use.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Skyvern supports proxy configuration at the browser level through Playwright.
|
||||
|
||||
### Environment variable approach
|
||||
|
||||
Set proxy configuration in your `.env` file:
|
||||
|
||||
```bash .env
|
||||
ENABLE_PROXY=true
|
||||
|
||||
# Single proxy
|
||||
HOSTED_PROXY_POOL=http://user:pass@proxy.example.com:8080
|
||||
|
||||
# Multiple proxies: Skyvern randomly selects one per browser session
|
||||
HOSTED_PROXY_POOL=http://user:pass@proxy1.example.com:8080,http://user:pass@proxy2.example.com:8080
|
||||
```
|
||||
|
||||
<Note>
|
||||
Skyvern Cloud supports a `proxy_location` parameter on task requests for geographic targeting (e.g., `RESIDENTIAL_US`). This feature is not available in self-hosted deployments. All tasks use the proxy configured in `HOSTED_PROXY_POOL`.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Setting up a proxy provider
|
||||
|
||||
### Step 1: Choose a provider
|
||||
|
||||
For browser automation, residential proxies work best. See [proxy types](#proxy-types) above.
|
||||
|
||||
### Step 2: Configure Skyvern
|
||||
|
||||
Add your proxy to the environment:
|
||||
|
||||
```bash .env
|
||||
ENABLE_PROXY=true
|
||||
HOSTED_PROXY_POOL=http://username:password@proxy.provider.com:8080
|
||||
```
|
||||
|
||||
### Step 3: Test the connection
|
||||
|
||||
Run a simple task that checks your IP:
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8000/v1/tasks \
|
||||
-H "x-api-key: YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "What is the IP address shown on this page?",
|
||||
"url": "https://whatismyipaddress.com"
|
||||
}'
|
||||
```
|
||||
|
||||
The task result should show an IP from your proxy provider, not your server's IP.
|
||||
|
||||
---
|
||||
|
||||
## Proxy authentication methods
|
||||
|
||||
### Basic auth (most common)
|
||||
|
||||
Include credentials in the URL:
|
||||
|
||||
```bash
|
||||
http://username:password@proxy.example.com:8080
|
||||
```
|
||||
|
||||
### IP whitelist
|
||||
|
||||
Some providers allow you to whitelist your server's IP instead of using credentials:
|
||||
|
||||
1. Get your server's public IP: `curl ifconfig.me`
|
||||
2. Add it to your proxy provider's whitelist
|
||||
3. Use the proxy without credentials:
|
||||
|
||||
```bash
|
||||
http://proxy.example.com:8080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Geographic targeting
|
||||
|
||||
If your proxy provider supports geographic targeting, configure it in your proxy URL. The exact format depends on the provider.
|
||||
|
||||
### Bright Data example
|
||||
|
||||
```bash
|
||||
# Target US residential
|
||||
http://user-country-us:pass@proxy.brightdata.com:8080
|
||||
|
||||
# Target specific US state
|
||||
http://user-country-us-state-california:pass@proxy.brightdata.com:8080
|
||||
```
|
||||
|
||||
### Oxylabs example
|
||||
|
||||
```bash
|
||||
# Target UK
|
||||
http://user-country-gb:pass@proxy.oxylabs.io:8080
|
||||
```
|
||||
|
||||
Check your provider's documentation for the exact format.
|
||||
|
||||
---
|
||||
|
||||
## Rotating proxies vs. sticky sessions
|
||||
|
||||
### Rotating (new IP per request)
|
||||
|
||||
Good for:
|
||||
- High-volume scraping
|
||||
- Avoiding per-IP rate limits
|
||||
- Tasks that don't need session persistence
|
||||
|
||||
### Sticky sessions (same IP for duration)
|
||||
|
||||
Good for:
|
||||
- Multi-step automations where the site tracks your session
|
||||
- Login flows
|
||||
- Sites that block IP changes mid-session
|
||||
|
||||
Most providers support sticky sessions via a session ID parameter:
|
||||
|
||||
```bash
|
||||
# Bright Data sticky session
|
||||
http://user-session-abc123:pass@proxy.brightdata.com:8080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Connection refused" or timeout errors
|
||||
|
||||
- Verify your proxy endpoint and credentials are correct
|
||||
- Check if your server can reach the proxy: `curl -x http://user:pass@proxy:port http://example.com`
|
||||
- Ensure your provider hasn't blocked your IP
|
||||
|
||||
### Target site still blocking requests
|
||||
|
||||
- Try a different proxy location
|
||||
- Use residential instead of datacenter proxies
|
||||
- Enable sticky sessions if the site tracks session changes
|
||||
- Verify the proxy is actually being used (check the IP)
|
||||
|
||||
### Slow performance
|
||||
|
||||
- Proxy overhead adds 100-500ms per request
|
||||
- Choose a proxy location geographically close to the target site
|
||||
- Use datacenter proxies for sites that allow them (faster than residential)
|
||||
|
||||
### High proxy costs
|
||||
|
||||
Residential proxy bandwidth is expensive. To reduce costs:
|
||||
- Disable video recording (reduces bandwidth)
|
||||
- Use datacenter proxies for sites that allow them
|
||||
- Cache resources where possible
|
||||
- Minimize unnecessary page loads
|
||||
|
||||
---
|
||||
|
||||
## Running without proxies
|
||||
|
||||
For internal tools or development, proxies aren't always necessary:
|
||||
|
||||
```bash .env
|
||||
ENABLE_PROXY=false
|
||||
```
|
||||
|
||||
Your browser traffic will originate directly from your server's IP. This works well for:
|
||||
- Internal applications
|
||||
- Development and testing
|
||||
- Sites that don't block datacenter traffic
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
|
||||
Store recordings and artifacts in S3 or Azure Blob
|
||||
</Card>
|
||||
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
|
||||
Deploy Skyvern at scale with Kubernetes
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,364 @@
|
||||
---
|
||||
title: Storage Configuration
|
||||
subtitle: Configure where Skyvern stores artifacts and recordings
|
||||
description: Configure Skyvern artifact storage using local filesystem, AWS S3, or Azure Blob Storage. Covers screenshots, browser recordings, HAR files, and extracted data storage for self-hosted deployments.
|
||||
slug: developers/self-hosted/storage
|
||||
keywords:
|
||||
- AWS S3
|
||||
- Azure Blob Storage
|
||||
- local filesystem
|
||||
- artifact storage
|
||||
- ARTIFACT_STORAGE_TYPE
|
||||
- bucket
|
||||
- container
|
||||
---
|
||||
|
||||
Skyvern generates several types of artifacts during task execution: screenshots, browser recordings, HAR files, and extracted data. By default, these are stored on the local filesystem. For production deployments, you can configure S3 or Azure Blob Storage.
|
||||
|
||||
## Storage types
|
||||
|
||||
Skyvern supports three storage backends:
|
||||
|
||||
| Type | `SKYVERN_STORAGE_TYPE` | Best for |
|
||||
|------|------------------------|----------|
|
||||
| Local filesystem | `local` | Development, single-server deployments |
|
||||
| AWS S3 | `s3` | Production on AWS, multi-server deployments |
|
||||
| Azure Blob | `azureblob` | Production on Azure |
|
||||
|
||||
---
|
||||
|
||||
## Local storage (default)
|
||||
|
||||
By default, Skyvern stores all artifacts in a local directory.
|
||||
|
||||
```bash .env
|
||||
SKYVERN_STORAGE_TYPE=local
|
||||
ARTIFACT_STORAGE_PATH=/data/artifacts
|
||||
VIDEO_PATH=/data/videos
|
||||
HAR_PATH=/data/har
|
||||
LOG_PATH=/data/log
|
||||
```
|
||||
|
||||
### Docker volume mounts
|
||||
|
||||
When using Docker Compose, these paths are mounted from your host:
|
||||
|
||||
```yaml docker-compose.yml
|
||||
volumes:
|
||||
- ./artifacts:/data/artifacts
|
||||
- ./videos:/data/videos
|
||||
- ./har:/data/har
|
||||
- ./log:/data/log
|
||||
```
|
||||
|
||||
### Limitations
|
||||
|
||||
Local storage works well for single-server deployments but has limitations:
|
||||
- Not accessible across multiple servers
|
||||
- No automatic backup or redundancy
|
||||
- Requires manual cleanup to manage disk space
|
||||
|
||||
---
|
||||
|
||||
## AWS S3
|
||||
|
||||
Store artifacts in S3 for durability, scalability, and access from multiple servers.
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash .env
|
||||
SKYVERN_STORAGE_TYPE=s3
|
||||
AWS_REGION=us-east-1
|
||||
AWS_S3_BUCKET_ARTIFACTS=your-skyvern-artifacts
|
||||
AWS_S3_BUCKET_SCREENSHOTS=your-skyvern-screenshots
|
||||
AWS_S3_BUCKET_BROWSER_SESSIONS=your-skyvern-browser-sessions
|
||||
AWS_S3_BUCKET_UPLOADS=your-skyvern-uploads
|
||||
|
||||
# Pre-signed URL expiration (seconds) - default 24 hours
|
||||
PRESIGNED_URL_EXPIRATION=86400
|
||||
|
||||
# Maximum upload file size (bytes) - default 10MB
|
||||
MAX_UPLOAD_FILE_SIZE=10485760
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Skyvern uses the standard AWS credential chain. Configure credentials using one of these methods:
|
||||
|
||||
**Environment variables:**
|
||||
|
||||
```bash .env
|
||||
AWS_ACCESS_KEY_ID=AKIA...
|
||||
AWS_SECRET_ACCESS_KEY=...
|
||||
```
|
||||
|
||||
**IAM role (recommended for EC2/ECS/EKS):**
|
||||
|
||||
Attach an IAM role with S3 permissions to your instance or pod. No credentials needed in environment.
|
||||
|
||||
**AWS profile:**
|
||||
|
||||
```bash .env
|
||||
AWS_PROFILE=your-profile-name
|
||||
```
|
||||
|
||||
### Required IAM permissions
|
||||
|
||||
Create an IAM policy with these permissions:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:GetObject",
|
||||
"s3:PutObject",
|
||||
"s3:DeleteObject",
|
||||
"s3:ListBucket"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::your-skyvern-artifacts",
|
||||
"arn:aws:s3:::your-skyvern-artifacts/*",
|
||||
"arn:aws:s3:::your-skyvern-screenshots",
|
||||
"arn:aws:s3:::your-skyvern-screenshots/*",
|
||||
"arn:aws:s3:::your-skyvern-browser-sessions",
|
||||
"arn:aws:s3:::your-skyvern-browser-sessions/*",
|
||||
"arn:aws:s3:::your-skyvern-uploads",
|
||||
"arn:aws:s3:::your-skyvern-uploads/*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Creating the buckets
|
||||
|
||||
Create the S3 buckets in your AWS account:
|
||||
|
||||
```bash
|
||||
aws s3 mb s3://your-skyvern-artifacts --region us-east-1
|
||||
aws s3 mb s3://your-skyvern-screenshots --region us-east-1
|
||||
aws s3 mb s3://your-skyvern-browser-sessions --region us-east-1
|
||||
aws s3 mb s3://your-skyvern-uploads --region us-east-1
|
||||
```
|
||||
|
||||
<Note>
|
||||
Bucket names must be globally unique across all AWS accounts. Add a unique prefix or suffix (e.g., your company name or a random string).
|
||||
</Note>
|
||||
|
||||
### Bucket configuration recommendations
|
||||
|
||||
**Lifecycle rules:** Configure automatic deletion of old artifacts to control costs.
|
||||
|
||||
```bash
|
||||
aws s3api put-bucket-lifecycle-configuration \
|
||||
--bucket your-skyvern-artifacts \
|
||||
--lifecycle-configuration '{
|
||||
"Rules": [
|
||||
{
|
||||
"ID": "DeleteOldArtifacts",
|
||||
"Status": "Enabled",
|
||||
"Filter": {},
|
||||
"Expiration": {
|
||||
"Days": 30
|
||||
}
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
**Encryption:** Enable server-side encryption for data at rest.
|
||||
|
||||
**Access logging:** Enable access logging for audit trails.
|
||||
|
||||
---
|
||||
|
||||
## Azure Blob Storage
|
||||
|
||||
Store artifacts in Azure Blob Storage for Azure-based deployments.
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash .env
|
||||
SKYVERN_STORAGE_TYPE=azureblob
|
||||
AZURE_STORAGE_ACCOUNT_NAME=yourstorageaccount
|
||||
AZURE_STORAGE_ACCOUNT_KEY=your-storage-account-key
|
||||
AZURE_STORAGE_CONTAINER_ARTIFACTS=skyvern-artifacts
|
||||
AZURE_STORAGE_CONTAINER_SCREENSHOTS=skyvern-screenshots
|
||||
AZURE_STORAGE_CONTAINER_BROWSER_SESSIONS=skyvern-browser-sessions
|
||||
AZURE_STORAGE_CONTAINER_UPLOADS=skyvern-uploads
|
||||
|
||||
# Pre-signed URL expiration (seconds) - default 24 hours
|
||||
PRESIGNED_URL_EXPIRATION=86400
|
||||
|
||||
# Maximum upload file size (bytes) - default 10MB
|
||||
MAX_UPLOAD_FILE_SIZE=10485760
|
||||
```
|
||||
|
||||
### Creating the storage account and containers
|
||||
|
||||
Using Azure CLI:
|
||||
|
||||
```bash
|
||||
# Create resource group
|
||||
az group create --name skyvern-rg --location eastus
|
||||
|
||||
# Create storage account
|
||||
az storage account create \
|
||||
--name yourstorageaccount \
|
||||
--resource-group skyvern-rg \
|
||||
--location eastus \
|
||||
--sku Standard_LRS
|
||||
|
||||
# Get the account key
|
||||
az storage account keys list \
|
||||
--account-name yourstorageaccount \
|
||||
--resource-group skyvern-rg \
|
||||
--query '[0].value' -o tsv
|
||||
|
||||
# Create containers
|
||||
az storage container create --name skyvern-artifacts --account-name yourstorageaccount
|
||||
az storage container create --name skyvern-screenshots --account-name yourstorageaccount
|
||||
az storage container create --name skyvern-browser-sessions --account-name yourstorageaccount
|
||||
az storage container create --name skyvern-uploads --account-name yourstorageaccount
|
||||
```
|
||||
|
||||
### Using Managed Identity (recommended)
|
||||
|
||||
For Azure VMs or AKS, use Managed Identity instead of storage account keys:
|
||||
|
||||
1. Enable Managed Identity on your VM or AKS cluster
|
||||
2. Grant the identity "Storage Blob Data Contributor" role on the storage account
|
||||
3. Omit `AZURE_STORAGE_ACCOUNT_KEY` from your configuration
|
||||
|
||||
---
|
||||
|
||||
## What gets stored where
|
||||
|
||||
| Artifact type | S3 bucket / Azure container | Contents |
|
||||
|---------------|---------------------------|----------|
|
||||
| Artifacts | `*-artifacts` | Extracted data, HTML snapshots, logs |
|
||||
| Screenshots | `*-screenshots` | Page screenshots at each step |
|
||||
| Browser Sessions | `*-browser-sessions` | Saved browser state for profiles |
|
||||
| Uploads | `*-uploads` | User-uploaded files for workflows |
|
||||
|
||||
Videos (recordings) are currently always stored locally in `VIDEO_PATH` regardless of storage type.
|
||||
|
||||
---
|
||||
|
||||
## Pre-signed URLs
|
||||
|
||||
When artifacts are stored in S3 or Azure Blob, Skyvern generates pre-signed URLs for access. These URLs:
|
||||
|
||||
- Expire after `PRESIGNED_URL_EXPIRATION` seconds (default: 24 hours)
|
||||
- Allow direct download without additional authentication
|
||||
- Are included in task responses (`recording_url`, `screenshot_urls`)
|
||||
|
||||
Adjust the expiration based on your needs:
|
||||
|
||||
```bash .env
|
||||
# 1 hour
|
||||
PRESIGNED_URL_EXPIRATION=3600
|
||||
|
||||
# 7 days
|
||||
PRESIGNED_URL_EXPIRATION=604800
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migrating from local to cloud storage
|
||||
|
||||
To migrate existing artifacts from local storage to S3 or Azure:
|
||||
|
||||
### S3
|
||||
|
||||
```bash
|
||||
# Sync local artifacts to S3
|
||||
aws s3 sync ./artifacts s3://your-skyvern-artifacts/
|
||||
|
||||
# Update configuration
|
||||
# SKYVERN_STORAGE_TYPE=s3
|
||||
# ...
|
||||
|
||||
# Restart Skyvern
|
||||
docker compose restart skyvern
|
||||
```
|
||||
|
||||
### Azure
|
||||
|
||||
```bash
|
||||
# Install azcopy
|
||||
# https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10
|
||||
|
||||
# Sync local artifacts to Azure
|
||||
azcopy copy './artifacts/*' 'https://yourstorageaccount.blob.core.windows.net/skyvern-artifacts' --recursive
|
||||
|
||||
# Update configuration and restart
|
||||
```
|
||||
|
||||
<Warning>
|
||||
After migration, new artifacts will be stored in cloud storage, but existing local artifacts won't be automatically moved. The sync is a one-time operation.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Disk space management
|
||||
|
||||
### Local storage
|
||||
|
||||
Monitor disk usage and clean up old artifacts periodically:
|
||||
|
||||
```bash
|
||||
# Check disk usage
|
||||
du -sh ./artifacts ./videos ./har ./log
|
||||
|
||||
# Remove artifacts older than 30 days
|
||||
find ./artifacts -type f -mtime +30 -delete
|
||||
find ./videos -type f -mtime +30 -delete
|
||||
```
|
||||
|
||||
### Cloud storage
|
||||
|
||||
Use lifecycle policies to automatically delete old objects:
|
||||
|
||||
**S3:** Configure lifecycle rules to expire objects after N days.
|
||||
|
||||
**Azure:** Configure lifecycle management policies in the Azure portal or via CLI.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Access Denied" errors
|
||||
|
||||
- Verify your credentials are correct
|
||||
- Check IAM permissions include all required actions
|
||||
- Ensure the buckets/containers exist
|
||||
- For S3, verify the AWS region matches your bucket location
|
||||
|
||||
### Pre-signed URLs not working
|
||||
|
||||
- Check that `PRESIGNED_URL_EXPIRATION` hasn't elapsed
|
||||
- Verify bucket policy allows public access to pre-signed URLs
|
||||
- For S3, ensure the bucket isn't blocking public access if needed
|
||||
|
||||
### Artifacts not appearing
|
||||
|
||||
- Check Skyvern logs for storage errors: `docker compose logs skyvern | grep -i storage`
|
||||
- Verify the storage type is correctly set: `SKYVERN_STORAGE_TYPE`
|
||||
- Ensure network connectivity to the storage endpoint
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
|
||||
Return to the Docker setup guide
|
||||
</Card>
|
||||
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
|
||||
Deploy Skyvern at scale
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user