Skip to content

Automate browser based workflows with AI

Fix PyPI quickstart wheel assets (#5867)

Marc Kelechava6e95a42fe672
diff --git a/docs/developers/browser-automations/overview.mdx b/docs/developers/browser-automations/overview.mdx
index 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.mdx
index 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 p
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 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 Skyvern
diff --git a/docs/developers/self-hosted/overview.mdx b/docs/developers/self-hosted/overview.mdx
index 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 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
@@ -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 method
diff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdx
index 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 Python
import 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.mdx
index 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.
```python
from skyvern import Skyvern
diff --git a/docs/snippets/mcp-content.mdx b/docs/snippets/mcp-content.mdx
index 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 mcporter
After 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:
```bash
skyvern 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.toml
index 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.tsx
index 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.tsx
index 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.py
index 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_var
def 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.py
index 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 services
if run_local:
diff --git a/skyvern/client/core/client_wrapper.py b/skyvern/client/core/client_wrapper.py
index 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__.py
index 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_config
from alembic import command
from alembic.config import Config
-
- # Import here to avoid circular import (config -> utils -> analytics -> config)
from skyvern.analytics import capture_setup_error, capture_setup_event
from skyvern.config import Settings, _ensure_sqlite_dir
from skyvern.forge.sdk.settings_manager import SettingsManager
# Reload settings so env vars set by setup_postgresql() are picked up.
refreshed = Settings()
+ skyvern_config.settings = refreshed
SettingsManager.set_settings(refreshed)
_ensure_sqlite_dir(refreshed.DATABASE_STRING)
diff --git a/uv.lock b/uv.lock
index 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" },