Skip to main content

​
Overview

The Skyvern TypeScript SDK provides a Playwright-compatible interface with AI-powered browser automation capabilities. It combines traditional browser automation with AI-powered task execution, allowing you to use natural language prompts alongside standard Playwright methods.

​
Installation

npm install @skyvern/client

​
Initialization

​
Remote Mode (Skyvern Cloud)

Connect to Skyvern Cloud or a self-hosted instance: 
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "your-api-key" });
Options:
  • apiKey (string, required): API key for authenticating with Skyvern. Get yours at app.skyvern.com/settings
  • environment (SkyvernEnvironment, optional): The Skyvern environment to connect to
    • SkyvernEnvironment.Cloud (default) - Skyvern Cloud
    • SkyvernEnvironment.Staging - Staging environment
  • baseUrl (string, optional): Override the base URL for the Skyvern API
  • timeout (number, optional): Timeout in milliseconds for API requests
  • maxRetries (number, optional): Maximum number of request retries

​
Browser Management

​
Launch Cloud Browser

Launch a new cloud-hosted browser session: 
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
Options:
  • timeout (number, optional): Timeout in minutes for the session (between 5-1440, default: 60)
  • proxyLocation (ProxyLocation, optional): Geographic proxy location for browser traffic (Skyvern Cloud only)

​
Use Cloud Browser

Get or create a cloud browser session (reuses existing session if available): 
const browser = await skyvern.useCloudBrowser();
const page = await browser.getWorkingPage();
Options: Same as launchCloudBrowser()

​
Connect to Existing Cloud Session

Connect to an existing cloud browser session by ID: 
const browser = await skyvern.connectToCloudBrowserSession("browser_session_id");
const page = await browser.getWorkingPage();
Parameters:
  • browserSessionId (string, required): The ID of the cloud browser session

​
Connect to Browser via CDP

Connect to an existing browser via Chrome DevTools Protocol: 
const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
const page = await browser.getWorkingPage();
Parameters:
  • cdpUrl (string, required): The CDP WebSocket URL

​
Task Execution

​
Run Task

Execute a one-off AI-powered browser automation task: 
const taskRun = await skyvern.runTask({
  prompt: "Find the top post on hackernews today",
  url: "https://news.ycombinator.com",
  waitForCompletion: true,
});

console.log(taskRun.status);  // "completed", "failed", etc.
console.log(taskRun.extracted_information);  // Extracted data
Options:
  • prompt (string, required): Natural language description of the task
  • engine (RunEngine, optional): Execution engine
  • model (Record<string, unknown>, optional): LLM model configuration
  • url (string, optional): Starting URL for the task
  • webhookUrl (string, optional): URL for webhook notifications
  • totpIdentifier (string, optional): TOTP identifier for 2FA
  • totpUrl (string, optional): URL to fetch TOTP codes
  • title (string, optional): Human-readable title for the task
  • errorCodeMapping (Record<string, string>, optional): Custom error code mappings
  • dataExtractionSchema (Record<string, unknown> | string, optional): Schema for extracted data
  • proxyLocation (ProxyLocation, optional): Geographic proxy location
  • maxSteps (number, optional): Maximum number of steps
  • waitForCompletion (boolean, optional): Wait for task to complete (default: false)
  • timeout (number, optional): Timeout in seconds (default: 1800)
  • browserSessionId (string, optional): Use existing browser session
  • userAgent (string, optional): Custom user agent
  • extraHttpHeaders (Record<string, string>, optional): Additional HTTP headers
Returns: HttpResponsePromise<TaskRunResponse> with execution results Data Extraction Example: 
const taskRun = await skyvern.runTask({
  prompt: "Find the top post on hackernews today",
  url: "https://news.ycombinator.com",
  dataExtractionSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Post title" },
      url: { type: "string", description: "Post URL" },
      points: { type: "integer", description: "Post points" },
    },
  },
  waitForCompletion: true,
});

console.log(taskRun.extracted_information);

​
Run Workflow

Execute a pre-defined workflow: 
const workflowRun = await skyvern.runWorkflow({
  workflowId: "wkfl_123",
  parameters: { userEmail: "[email protected]" },
  waitForCompletion: true,
});

console.log(workflowRun.status);
Options:
  • workflowId (string, required): ID of the workflow to execute
  • parameters (Record<string, unknown>, optional): Workflow parameters
  • template (boolean, optional): Whether this is a template
  • title (string, optional): Human-readable title
  • proxyLocation (ProxyLocation, optional): Geographic proxy location
  • webhookUrl (string, optional): Webhook notification URL
  • totpUrl (string, optional): TOTP URL
  • totpIdentifier (string, optional): TOTP identifier
  • browserSessionId (string, optional): Use existing browser session
  • maxStepsOverride (number, optional): Override max steps
  • userAgent (string, optional): Custom user agent
  • browserProfileId (string, optional): Browser profile ID
  • maxScreenshotScrolls (number, optional): Maximum screenshot scrolls
  • extraHttpHeaders (Record<string, string>, optional): Additional headers
  • browserAddress (string, optional): Custom browser address
  • aiFallback (boolean, optional): Enable AI fallback
  • runWith (string, optional): Run with specific configuration
  • waitForCompletion (boolean, optional): Wait for completion (default: false)
  • timeout (number, optional): Timeout in seconds (default: 1800)
Returns: HttpResponsePromise<WorkflowRunResponse> with execution results

​
Login

Execute a login workflow with stored credentials: 
const workflowRun = await skyvern.login({
  credentialType: "skyvern",
  credentialId: "cred_123",
  url: "https://example.com/login",
  waitForCompletion: true,
});
Options:
  • credentialType (CredentialType, required): Type of credential
    • "skyvern" - Skyvern-stored credentials
    • "bitwarden" - Bitwarden credentials
    • "1password" - 1Password credentials
    • "azure_vault" - Azure Key Vault credentials
  • url (string, optional): Login page URL
  • credentialId (string, optional): Skyvern credential ID (for "skyvern" type)
  • bitwardenCollectionId (string, optional): Bitwarden collection ID
  • bitwardenItemId (string, optional): Bitwarden item ID
  • onepasswordVaultId (string, optional): 1Password vault ID
  • onepasswordItemId (string, optional): 1Password item ID
  • azureVaultName (string, optional): Azure vault name
  • azureVaultUsernameKey (string, optional): Azure username key
  • azureVaultPasswordKey (string, optional): Azure password key
  • azureVaultTotpSecretKey (string, optional): Azure TOTP secret key
  • prompt (string, optional): Custom login instructions
  • webhookUrl (string, optional): Webhook notification URL
  • proxyLocation (ProxyLocation, optional): Geographic proxy location
  • totpIdentifier (string, optional): TOTP identifier
  • totpUrl (string, optional): TOTP URL
  • browserSessionId (string, optional): Use existing browser session
  • browserAddress (string, optional): Custom browser address
  • extraHttpHeaders (Record<string, string>, optional): Additional headers
  • waitForCompletion (boolean, optional): Wait for completion (default: false)
  • timeout (number, optional): Timeout in seconds (default: 1800)
Returns: HttpResponsePromise<WorkflowRunResponse> with execution results

​
Download Files

Execute a file download workflow: 
const workflowRun = await skyvern.downloadFiles({
  navigationGoal: "Navigate to invoices and download latest invoice",
  url: "https://example.com/invoices",
  waitForCompletion: true,
});
Options:
  • navigationGoal (string, required): Instructions for navigating to and downloading the file
  • url (string, optional): Starting URL
  • downloadSuffix (string, optional): Suffix or filename for downloaded file
  • downloadTimeout (number, optional): Timeout in seconds for download
  • maxStepsPerRun (number, optional): Maximum steps to execute
  • webhookUrl (string, optional): Webhook notification URL
  • totpIdentifier (string, optional): TOTP identifier
  • totpUrl (string, optional): TOTP URL
  • browserSessionId (string, optional): Use existing browser session
  • browserAddress (string, optional): Custom browser address
  • extraHttpHeaders (Record<string, string>, optional): Additional headers
  • waitForCompletion (boolean, optional): Wait for completion (default: false)
  • timeout (number, optional): Timeout in seconds (default: 1800)
Returns: HttpResponsePromise<WorkflowRunResponse> with execution results

​
Resource Management

​
Close Resources

Close all browsers and release resources: 
await skyvern.close();

​
Properties

​
environment

Get the current Skyvern environment: 
const env = skyvern.environment;
// Returns: SkyvernEnvironment.Cloud, .Staging, or custom string

​
Complete Example

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

async function main() {
  // Initialize Skyvern
  const skyvern = new Skyvern({ apiKey: "your-api-key" });
  
  // Create credentials
  const credential = await skyvern.createCredential({
    name: "my_user",
    credentialType: "password",
    credential: { username: "[email protected]", password: "secret" },
  });
  
  // Launch cloud browser
  const browser = await skyvern.launchCloudBrowser();
  const page = await browser.getWorkingPage();
  
  // Mix traditional Playwright with AI
  await page.goto("https://example.com");
  
  // AI-powered login
  await page.agent.login("skyvern", {
    credentialId: credential.credential_id,
  });
  
  // Traditional browser control
  await page.click("#invoices-button");
  await page.fill("#search", "my invoice");
  
  // Take screenshot
  await page.screenshot({ path: "screenshot.png", fullPage: true });
  
  // Close browser
  await browser.close();
  await skyvern.close();
}

main();

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us