Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Fix PyPI quickstart wheel assets (#5867)
Marc Kelechava6e95a42fe672
diff --git a/docs/developers/browser-automations/overview.mdx b/docs/developers/browser-automations/overview.mdxindex 19e971eee..9dbae789d 100644--- a/docs/developers/browser-automations/overview.mdx+++ b/docs/developers/browser-automations/overview.mdx@@ -51,6 +51,8 @@ npm install @skyvern/client```</CodeGroup>+`pip install skyvern` is enough for Skyvern Cloud and remote API usage. If you are using `Skyvern.local()` or 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>diff --git a/docs/developers/getting-started/quickstart.mdx b/docs/developers/getting-started/quickstart.mdxindex cd96a1da6..04ed3fde9 100644--- a/docs/developers/getting-started/quickstart.mdx+++ b/docs/developers/getting-started/quickstart.mdx@@ -41,6 +41,10 @@ npm install @skyvern/client```</CodeGroup>+<Info>+`pip install skyvern` is the lightweight Python SDK for Skyvern Cloud and remote API usage. If you are setting up a local Skyvern server, self-hosted instance, `Skyvern.local()`, 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:@@ -192,12 +196,13 @@ This is invaluable for debugging and understanding how Skyvern interprets your pYou 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 SDK installed (`pip install skyvern`)+- 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.+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 Skyverndiff --git a/docs/developers/self-hosted/overview.mdx b/docs/developers/self-hosted/overview.mdxindex d5ed59e77..830290e71 100644--- a/docs/developers/self-hosted/overview.mdx+++ b/docs/developers/self-hosted/overview.mdx@@ -23,12 +23,14 @@ Self-hosted Skyvern has four components running on your infrastructure:flowchart LRsubgraph Your InfrastructureAPI[Skyvern API Server<br/>+ Embedded Browser]+ UI[Skyvern Web UI]DB[(PostgreSQL)]endLLM[LLM Provider]Sites[Target Websites]+ UI <--> APIAPI <--> DBAPI <--> LLMAPI <--> Sites@@ -37,6 +39,7 @@ flowchart LR| 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) |@@ -86,7 +89,11 @@ Before deploying, ensure you have: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 the `pip install skyvern` 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 the pip path, run `skyvern quickstart --database-string=postgresql+psycopg://user:pass@host:5432/dbname`.+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 methoddiff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdxindex 7f07dab8e..9ea68e407 100644--- a/docs/sdk-reference/complete-reference.mdx+++ b/docs/sdk-reference/complete-reference.mdx@@ -32,6 +32,10 @@ npm install @skyvern/client```</CodeGroup>+<Note>+`pip install skyvern` is the lightweight SDK for Skyvern Cloud and remote API calls. Local server features such as `Skyvern.local()`, local browser control, and local stdio MCP require `pip install "skyvern[server]"`. Guided quickstart and migrations currently require Docker Compose or a source checkout.+</Note>+<CodeGroup>```python Pythonimport asyncio@@ -76,7 +80,7 @@ Skyvern(timeout: float | None = None, # HTTP request timeout (seconds))-# Local mode (Python only - runs entirely on your machine, reads .env)+# Local mode (Python only - requires pip install "skyvern[server]")client = Skyvern.local()```@@ -689,6 +693,6 @@ request_options=RequestOptions(- `browser_profile_id` works with `run_workflow` only - silently ignored by `run_task`.- Python `download_files` does not support `wait_for_completion` - poll manually or use webhooks.- Only workflow runs with `persist_browser_session=True` produce archives for profile creation.-- `launch_local_browser` requires Python local mode (`Skyvern.local()`).+- `launch_local_browser` requires Python local mode (`Skyvern.local()`) and the `skyvern[server]` extra.- `page.agent` methods always wait for completion.- Python-only features: `launch_local_browser`, `get_page_for`, `locator`/`AILocator`, `type`, `hover`, `scroll`, `upload_file` (page-level), form automation (`fill_form`, `fill_multipage_form`, `fill_from_mapping`, `extract_form_fields`, `validate_mapping`, `fill_autocomplete`), iframe management (`frame_switch`, `frame_main`, `frame_list`).diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdxindex f8a2022bc..6b156f50e 100644--- a/docs/sdk-reference/overview.mdx+++ b/docs/sdk-reference/overview.mdx@@ -32,7 +32,7 @@ npm install @skyvern/client</CodeGroup><Note>-If you hit Python version errors, use `pipx install skyvern` to install in an isolated environment.+`pip install skyvern` is the lightweight SDK for Skyvern Cloud and remote API calls. Local server features such as `Skyvern.local()`, local browser control, and local stdio MCP require `pip install "skyvern[server]"`. Guided quickstart and migrations currently require Docker Compose or a source checkout.</Note>---@@ -144,7 +144,7 @@ const skyvern = new Skyvern({Run Skyvern entirely on your machine - no cloud, no network calls. `Skyvern.local()` reads your `.env` file, boots the engine in-process, and connects the client to it.-**Prerequisite:** Run `skyvern quickstart` once to create the `.env` file with your database connection and LLM API keys.+**Prerequisite:** Install the server extra with `pip install "skyvern[server]"` and initialize local configuration from Docker Compose or a source checkout.```pythonfrom skyvern import Skyverndiff --git a/docs/snippets/mcp-content.mdx b/docs/snippets/mcp-content.mdxindex bc8c3a5c2..3df3883a3 100644--- a/docs/snippets/mcp-content.mdx+++ b/docs/snippets/mcp-content.mdx@@ -24,7 +24,7 @@ You have three ways to connect a client to Skyvern:| | OAuth (sign in with browser) | API key | Local mode ||---|---|---|---|| **Best for** | Claude Code, Codex CLI, Cursor, and other clients that support MCP OAuth | Claude Desktop, Windsurf, Hermes, OpenClaw, headless/CI flows, or any client where you prefer a static key | Self-hosting Skyvern |-| **Install required** | None | None | Python 3.11+ and `pip install skyvern` |+| **Install required** | None | None | Python 3.11+ and `pip install "skyvern[server]"` || **Credential** | Browser sign-in with your Skyvern account | API key from [app.skyvern.com](https://app.skyvern.com) | API key from your self-hosted instance || **Where it runs** | Directly against Skyvern Cloud over HTTPS | Directly against Skyvern Cloud over HTTPS | Local Python process talking to your Skyvern server |@@ -289,7 +289,7 @@ skyvern setup mcporterAfter setup, restart your MCP client. Skyvern should appear as an MCP server and is ready for browser tasks.<Tip>-Prefer a CLI? For Skyvern Cloud, `pip install skyvern` then run `skyvern setup`. For the local self-hosted path, run `skyvern quickstart` or `skyvern init` and choose Claude Code during the MCP step.+Prefer a CLI? For Skyvern Cloud, `pip install skyvern` then run `skyvern setup`. For the local self-hosted path, use Docker Compose or a source checkout, then run `skyvern quickstart` or `skyvern init` and choose Claude Code during the MCP step.</Tip>## Switch an existing MCP config@@ -321,19 +321,19 @@ If a config file exists but does not already contain a Skyvern entry, run `skyve## Alternative: Local mode (self-hosted)-Use this if you are self-hosting Skyvern and want the MCP server to talk to your own instance instead of Skyvern Cloud. This runs a lightweight Python process on your machine that connects to your local Skyvern server.+Use this if you are self-hosting Skyvern and want the MCP server to talk to your own instance instead of Skyvern Cloud. This runs a local Python process on your machine that connects to your local Skyvern server.<Tip title="Supported Python Versions" icon="fa-brands fa-python">Local mode requires Python 3.11, 3.12, or 3.13.</Tip>```bash-pip install skyvern+pip install ".[server]"```### Recommended local Claude Code flow-Run the setup wizard from your project or repo root:+Run the setup wizard from a Skyvern source checkout or Docker Compose setup:```bashskyvern quickstart@@ -425,7 +425,7 @@ Replace `/usr/bin/python3` with the output of `which python3`. For Skyvern Cloud</Tabs><Tip>-`skyvern init` and `skyvern quickstart` can write the local MCP config for you. In a project directory, choosing Claude Code defaults to project-local `.mcp.json` and installs `.claude/skills/qa`.+From Docker Compose or a source checkout, `skyvern init` and `skyvern quickstart` can write the local MCP config for you. In a project directory, choosing Claude Code defaults to project-local `.mcp.json` and installs `.claude/skills/qa`.</Tip><Accordion title="Config file locations by client">@@ -496,10 +496,10 @@ Private Claude Desktop bundles do not auto-update. Download the latest [`skyvern## QA your frontend changes-For the local self-hosted path, run `skyvern quickstart` or `skyvern init`, choose `local`, then choose `Claude Code` during the MCP step. That writes local stdio MCP config and installs Claude Code skills, including `/qa`, which reads your git diff, generates browser tests, and runs them against your dev server.+For the local self-hosted path, use Docker Compose or a Skyvern source checkout, then run `skyvern quickstart` or `skyvern init`, choose `local`, then choose `Claude Code` during the MCP step. That writes local stdio MCP config and installs Claude Code skills, including `/qa`, which reads your git diff, generates browser tests, and runs them against your dev server.```bash-pip install skyvern+pip install ".[server]"skyvern quickstart# or: skyvern init```diff --git a/pyproject.toml b/pyproject.tomlindex 3b4ebfdb4..9d8406b54 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,6 +1,6 @@[project]name = "skyvern"-version = "1.0.33"+version = "1.0.34"description = ""authors = [{ name = "Skyvern AI", email = "[email protected]" }]requires-python = ">=3.11,<3.14"@@ -166,10 +166,14 @@ exclude = ["skyvern-frontend/node_modules","skyvern-frontend/dist",]+[tool.hatch.build.targets.sdist.force-include]+"alembic" = "alembic"[tool.hatch.build.targets.wheel]include = ["skyvern",]+[tool.hatch.build.targets.wheel.force-include]+"alembic" = "alembic"[tool.uv]# Supply chain quarantine: block packages published less than 7 days ago.diff --git a/skyvern-frontend/src/routes/workflows/WorkflowRun.tsx b/skyvern-frontend/src/routes/workflows/WorkflowRun.tsxindex 238a29e3a..d017c9653 100644--- a/skyvern-frontend/src/routes/workflows/WorkflowRun.tsx+++ b/skyvern-frontend/src/routes/workflows/WorkflowRun.tsx@@ -64,6 +64,7 @@ function WorkflowRun() {const isEmbedded = embed === "true";const active = searchParams.get("active");const workflowRunId = useFirstParam("workflowRunId", "runId");+ const workflowPermanentIdParam = useFirstParam("workflowPermanentId");const credentialGetter = useCredentialGetter();const apiCredential = useApiCredential();const queryClient = useQueryClient();@@ -77,7 +78,7 @@ function WorkflowRun() {const status = (error as AxiosError | undefined)?.response?.status;const workflow = workflowRun?.workflow;- const workflowPermanentId = workflow?.workflow_permanent_id;+ const workflowPermanentId = workflowPermanentIdParam;const cacheKey = workflow?.cache_key ?? "";const isFinalized = workflowRun ? statusIsFinalized(workflowRun) : null;const isWorkflowDeleted = Boolean(workflow?.deleted_at);diff --git a/skyvern-frontend/src/routes/workflows/WorkflowRunParameters.tsx b/skyvern-frontend/src/routes/workflows/WorkflowRunParameters.tsxindex 540785614..e6264309d 100644--- a/skyvern-frontend/src/routes/workflows/WorkflowRunParameters.tsx+++ b/skyvern-frontend/src/routes/workflows/WorkflowRunParameters.tsx@@ -21,6 +21,7 @@ function WorkflowRunParameters() {.get(`/workflows/${workflowPermanentId}`).then((response) => response.data);},+ enabled: !!workflowPermanentId,refetchOnWindowFocus: false,});diff --git a/skyvern/cli/init_command.py b/skyvern/cli/init_command.pyindex 8bfcf3328..23d29444a 100644--- a/skyvern/cli/init_command.py+++ b/skyvern/cli/init_command.py@@ -21,6 +21,7 @@ from .llm_setup import setup_llm_providers, update_or_add_env_vardef init_env(no_postgres: bool = False,database_string: str = "",+ skip_browser_install: bool = False,) -> bool:"""Interactive initialization command for Skyvern."""console.print(@@ -172,24 +173,27 @@ def init_env()if run_local:- console.print("\n⬇️ [bold blue]Installing Chromium browser...[/bold blue]")- capture_setup_event("playwright-install-start")- with Progress(- SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console- ) as progress:- progress.add_task("[bold blue]Downloading Chromium, this may take a moment...", total=None)- try:- subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)- capture_setup_event("playwright-install-complete", success=True)- except subprocess.CalledProcessError as e:- capture_setup_event(- "playwright-install-fail",- success=False,- error_type="playwright_install_error",- error_message=e.stderr.strip() if e.stderr else str(e),- )- raise- console.print("✅ [green]Chromium installation complete.[/green]")+ if skip_browser_install:+ console.print("⏭️ [yellow]Skipping Chromium installation as requested.[/yellow]")+ else:+ console.print("\n⬇️ [bold blue]Installing Chromium browser...[/bold blue]")+ capture_setup_event("playwright-install-start")+ with Progress(+ SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console+ ) as progress:+ progress.add_task("[bold blue]Downloading Chromium, this may take a moment...", total=None)+ try:+ subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)+ capture_setup_event("playwright-install-complete", success=True)+ except subprocess.CalledProcessError as e:+ capture_setup_event(+ "playwright-install-fail",+ success=False,+ error_type="playwright_install_error",+ error_message=e.stderr.strip() if e.stderr else str(e),+ )+ raise+ console.print("✅ [green]Chromium installation complete.[/green]")console.print("\n🎉 [bold green]Skyvern setup complete![/bold green]")capture_setup_event("init-complete", success=True, extra_data={"mode": "local"})diff --git a/skyvern/cli/quickstart.py b/skyvern/cli/quickstart.pyindex 30d59b83e..cce3b6be4 100644--- a/skyvern/cli/quickstart.py+++ b/skyvern/cli/quickstart.py@@ -262,28 +262,11 @@ def quickstart(try:# Initialize Skyvern (pip install path)console.print("\n[bold blue]Initializing Skyvern...[/bold blue]")- run_local = init_env(no_postgres=no_postgres, database_string=database_string)-- # Skip browser installation if requested- if not skip_browser_install:- with Progress(- SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console- ) as progress:- progress.add_task("[bold blue]Installing Chromium browser...", total=None)- try:- subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)- console.print("✅ [green]Chromium installation complete.[/green]")- capture_setup_event("playwright-install-complete", success=True)- except subprocess.CalledProcessError as e:- capture_setup_event(- "playwright-install-fail",- success=False,- error_type="playwright_install_error",- error_message=e.stderr.strip() if e.stderr else str(e),- )- console.print(f"[yellow]Warning: Failed to install Chromium: {e.stderr}[/yellow]")- else:- console.print("⏭️ [yellow]Skipping Chromium installation as requested.[/yellow]")+ run_local = init_env(+ no_postgres=no_postgres,+ database_string=database_string,+ skip_browser_install=skip_browser_install,+ )# Start servicesif run_local:diff --git a/skyvern/client/core/client_wrapper.py b/skyvern/client/core/client_wrapper.pyindex 8eadebd11..37f2cdbcd 100644--- a/skyvern/client/core/client_wrapper.py+++ b/skyvern/client/core/client_wrapper.py@@ -22,10 +22,10 @@ class BaseClientWrapper:def get_headers(self) -> typing.Dict[str, str]:headers: typing.Dict[str, str] = {- "User-Agent": "skyvern/1.0.33",+ "User-Agent": "skyvern/1.0.34","X-Fern-Language": "Python","X-Fern-SDK-Name": "skyvern",- "X-Fern-SDK-Version": "1.0.33",+ "X-Fern-SDK-Version": "1.0.34",**(self.get_custom_headers() or {}),}if self._api_key is not None:diff --git a/skyvern/utils/__init__.py b/skyvern/utils/__init__.pyindex b6c867148..d1d353f33 100644--- a/skyvern/utils/__init__.py+++ b/skyvern/utils/__init__.py@@ -39,16 +39,18 @@ def migrate_db() -> None:if not migrations_path.is_dir():raise RuntimeError(_MISSING_MIGRATIONS_MESSAGE)+ # Keep these imports lazy: skyvern.config imports skyvern.utils.env_paths+ # while this module is initializing, and analytics also depends on config.+ import skyvern.config as skyvern_configfrom alembic import commandfrom alembic.config import Config-- # Import here to avoid circular import (config -> utils -> analytics -> config)from skyvern.analytics import capture_setup_error, capture_setup_eventfrom skyvern.config import Settings, _ensure_sqlite_dirfrom skyvern.forge.sdk.settings_manager import SettingsManager# Reload settings so env vars set by setup_postgresql() are picked up.refreshed = Settings()+ skyvern_config.settings = refreshedSettingsManager.set_settings(refreshed)_ensure_sqlite_dir(refreshed.DATABASE_STRING)diff --git a/uv.lock b/uv.lockindex 89996687d..90b514488 100644--- a/uv.lock+++ b/uv.lock@@ -5499,7 +5499,7 @@ wheels = [[[package]]name = "skyvern"-version = "1.0.33"+version = "1.0.34"source = { editable = "." }dependencies = [{ name = "cachetools" },