Skip to content

Automate browser based workflows with AI

Add interactive ngrok guided setup for browser serve --tunnel (#4986)

Marc Kelechava5a5db62bfa78
diff --git a/skyvern/cli/commands/browser.py b/skyvern/cli/commands/browser.py
index b96c41bce..5c452731a 100644
--- a/skyvern/cli/commands/browser.py
+++ b/skyvern/cli/commands/browser.py
@@ -2,7 +2,6 @@ from __future__ import annotations
import asyncio
import json
-import shutil
import subprocess
import sys
from dataclasses import asdict, dataclass
@@ -31,6 +30,7 @@ from skyvern.cli.core.guards import (
validate_button,
validate_wait_until,
)
+from skyvern.cli.core.ngrok import check_ngrok_auth, detect_ngrok, offer_install_ngrok, offer_setup_auth
from skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_list
from skyvern.cli.mcp_tools.browser import skyvern_login as tool_login
from skyvern.cli.mcp_tools.browser import skyvern_run_task as tool_run_task
@@ -1244,31 +1244,23 @@ async def _maybe_start_ngrok_tunnel(port: int, browser_path: str, *, auto: bool)
return None
# Check if ngrok is installed
- ngrok_path = shutil.which("ngrok")
+ ngrok_path = detect_ngrok()
if not ngrok_path:
- console.print()
- console.print(" [bold red]ngrok not found.[/bold red]")
- console.print()
- console.print(" [bold]1.[/bold] Install ngrok:")
- console.print(" [green]brew install ngrok[/green] [dim](macOS)[/dim]")
- console.print(" [cyan]https://ngrok.com/download[/cyan] [dim](other platforms)[/dim]")
- console.print()
- console.print(" [bold]2.[/bold] Sign up for a free account:")
- console.print(" [cyan]https://dashboard.ngrok.com/signup[/cyan]")
- console.print()
- console.print(" [bold]3.[/bold] Add your authtoken:")
- console.print(" [green]ngrok config add-authtoken <your-token>[/green]")
- console.print(
- " [dim]Get your token at[/dim] [cyan]https://dashboard.ngrok.com/get-started/your-authtoken[/cyan]"
- )
- console.print()
- console.print(" [bold]4.[/bold] Re-run:")
- console.print(" [green]skyvern browser serve --tunnel[/green]")
- console.print()
- if auto:
- # --tunnel was explicit — don't silently continue without a tunnel
- raise SystemExit(1)
- return None
+ # When auto=True (--tunnel in CI), skip interactive prompts and fail fast
+ ngrok_path = offer_install_ngrok(interactive=not auto)
+ if not ngrok_path:
+ if auto:
+ raise SystemExit(1)
+ return None
+
+ # Check if ngrok auth token is configured
+ # Note: check_ngrok_auth is best-effort (validates config syntax, not token
+ # validity). The real validation happens when ngrok tries to start a tunnel.
+ if not check_ngrok_auth(ngrok_path):
+ if not offer_setup_auth(ngrok_path, interactive=not auto):
+ if auto:
+ raise SystemExit(1)
+ return None
console.print()
console.print(f" Starting ngrok tunnel on port [cyan]{port}[/cyan]...")
diff --git a/skyvern/cli/core/ngrok.py b/skyvern/cli/core/ngrok.py
new file mode 100644
index 000000000..ff93edf8e
--- /dev/null
+++ b/skyvern/cli/core/ngrok.py
@@ -0,0 +1,153 @@
+"""ngrok detection, installation, and auth token setup helpers.
+
+Used by ``_maybe_start_ngrok_tunnel`` in ``skyvern.cli.commands.browser`` to
+provide an interactive guided setup when ngrok is missing or unconfigured.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import webbrowser
+
+from rich.prompt import Confirm, Prompt
+
+from skyvern.cli.console import console
+
+
+def detect_ngrok() -> str | None:
+ """Return the path to the ngrok binary, or ``None`` if not found."""
+ return shutil.which("ngrok")
+
+
+def detect_os() -> str:
+ """Return ``'macos'``, ``'linux'``, or ``'windows'``."""
+ system = platform.system().lower()
+ if system == "darwin":
+ return "macos"
+ if system == "linux":
+ return "linux"
+ return "windows"
+
+
+def offer_install_ngrok(*, interactive: bool = True) -> str | None:
+ """Interactively offer to install ngrok. Returns the path on success, else ``None``.
+
+ When *interactive* is ``False`` (e.g. ``--tunnel`` in CI), skip prompts
+ and just print the error message.
+ """
+ if not interactive:
+ console.print()
+ console.print(" [bold red]ngrok not found.[/bold red]")
+ console.print(" Install from: [cyan]https://ngrok.com/download[/cyan]")
+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")
+ console.print()
+ return None
+
+ os_type = detect_os()
+
+ # macOS: try Homebrew first
+ if os_type == "macos" and shutil.which("brew"):
+ want = Confirm.ask(
+ "[bold red]ngrok not found.[/bold red] Install via Homebrew?",
+ default=True,
+ )
+ if want:
+ try:
+ console.print(" Installing ngrok via Homebrew...")
+ subprocess.run(["brew", "install", "ngrok"], check=True)
+ path = shutil.which("ngrok")
+ if path:
+ console.print(" [green]ngrok installed successfully.[/green]")
+ return path
+ except subprocess.CalledProcessError as exc:
+ console.print(f" [red]Homebrew install failed (exit {exc.returncode}).[/red]")
+ # Fall through to download page
+ else:
+ # User declined brew — skip the redundant "ngrok not found" message
+ console.print()
+ console.print(" Install manually from: [cyan]https://ngrok.com/download[/cyan]")
+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")
+ console.print()
+ want_open = Confirm.ask("Open ngrok download page in browser?", default=True)
+ if want_open:
+ open_url("https://ngrok.com/download")
+ return None
+
+ # Fallback: direct the user to the download page
+ console.print()
+ console.print(" [bold red]ngrok not found.[/bold red]")
+ console.print(" Install from: [cyan]https://ngrok.com/download[/cyan]")
+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")
+ console.print()
+
+ want = Confirm.ask("Open ngrok download page in browser?", default=True)
+ if want:
+ open_url("https://ngrok.com/download")
+
+ return None
+
+
+def check_ngrok_auth(ngrok_path: str) -> bool:
+ """Return ``True`` if ngrok has a valid configuration with an auth token.
+
+ Note: ``ngrok config check`` validates config file syntax, not the presence
+ of an auth token specifically. Some ngrok versions exit 0 with no token.
+ This is a best-effort check — the real validation happens when ngrok tries
+ to start a tunnel.
+ """
+ try:
+ result = subprocess.run(
+ [ngrok_path, "config", "check"],
+ capture_output=True,
+ text=True,
+ timeout=5,
+ )
+ return result.returncode == 0
+ except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+ return False
+
+
+def offer_setup_auth(ngrok_path: str, *, interactive: bool = True) -> bool:
+ """Guide the user through configuring their ngrok auth token. Returns ``True`` on success.
+
+ When *interactive* is ``False`` (e.g. ``--tunnel`` in CI), skip prompts
+ and just print the error message.
+ """
+ console.print()
+ console.print(" [bold yellow]ngrok auth token not configured.[/bold yellow]")
+
+ if not interactive:
+ console.print(" Run: [green]ngrok config add-authtoken <your-token>[/green]")
+ console.print(" Get a token at: [cyan]https://dashboard.ngrok.com/get-started/your-authtoken[/cyan]")
+ console.print()
+ return False
+
+ console.print()
+
+ want = Confirm.ask("Open ngrok dashboard to get a free auth token?", default=True)
+ if want:
+ open_url("https://dashboard.ngrok.com/get-started/your-authtoken")
+
+ token = Prompt.ask("Paste your ngrok auth token (or press Enter to skip)", default="")
+ if not token.strip():
+ return False
+
+ result = subprocess.run(
+ [ngrok_path, "config", "add-authtoken", token.strip()],
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ if result.returncode == 0:
+ console.print(" [green]Auth token configured successfully.[/green]")
+ return True
+
+ console.print(f" [red]Failed to set auth token: {result.stderr.strip()}[/red]")
+ return False
+
+
+def open_url(url: str) -> None:
+ """Open *url* in the user's default browser."""
+ webbrowser.open(url)
diff --git a/tests/unit/test_ngrok_helpers.py b/tests/unit/test_ngrok_helpers.py
new file mode 100644
index 000000000..ec0ee1667
--- /dev/null
+++ b/tests/unit/test_ngrok_helpers.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import subprocess
+from unittest.mock import patch
+
+from skyvern.cli.core.ngrok import (
+ check_ngrok_auth,
+ detect_ngrok,
+ detect_os,
+ offer_install_ngrok,
+ offer_setup_auth,
+)
+
+
+def test_detect_ngrok_found() -> None:
+ with patch("skyvern.cli.core.ngrok.shutil.which", return_value="/usr/local/bin/ngrok"):
+ assert detect_ngrok() == "/usr/local/bin/ngrok"
+
+
+def test_detect_ngrok_missing() -> None:
+ with patch("skyvern.cli.core.ngrok.shutil.which", return_value=None):
+ assert detect_ngrok() is None
+
+
+def test_detect_os_platforms() -> None:
+ for system, expected in [("Darwin", "macos"), ("Linux", "linux"), ("Windows", "windows")]:
+ with patch("skyvern.cli.core.ngrok.platform.system", return_value=system):
+ assert detect_os() == expected
+
+
+def test_check_ngrok_auth_success() -> None:
+ with patch("skyvern.cli.core.ngrok.subprocess.run") as mock_run:
+ mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0)
+ assert check_ngrok_auth("/usr/local/bin/ngrok") is True
+
+
+def test_check_ngrok_auth_failures() -> None:
+ # Non-zero exit
+ with patch("skyvern.cli.core.ngrok.subprocess.run") as mock_run:
+ mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=1)
+ assert check_ngrok_auth("/usr/local/bin/ngrok") is False
+
+ # Timeout
+ with patch(
+ "skyvern.cli.core.ngrok.subprocess.run",
+ side_effect=subprocess.TimeoutExpired(cmd="ngrok", timeout=5),
+ ):
+ assert check_ngrok_auth("/usr/local/bin/ngrok") is False
+
+
+def test_offer_install_brew_success() -> None:
+ with (
+ patch("skyvern.cli.core.ngrok.detect_os", return_value="macos"),
+ patch("skyvern.cli.core.ngrok.shutil.which", side_effect=["/opt/homebrew/bin/brew", "/opt/homebrew/bin/ngrok"]),
+ patch("skyvern.cli.core.ngrok.subprocess.run", return_value=subprocess.CompletedProcess(args=[], returncode=0)),
+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=True),
+ ):
+ assert offer_install_ngrok() == "/opt/homebrew/bin/ngrok"
+
+
+def test_offer_install_brew_declined() -> None:
+ """When user declines brew, should show manual install info without redundant 'ngrok not found'."""
+ with (
+ patch("skyvern.cli.core.ngrok.detect_os", return_value="macos"),
+ patch("skyvern.cli.core.ngrok.shutil.which", return_value="/opt/homebrew/bin/brew"),
+ patch("skyvern.cli.core.ngrok.Confirm.ask", side_effect=[False, False]),
+ patch("skyvern.cli.core.ngrok.console") as mock_console,
+ ):
+ result = offer_install_ngrok()
+ assert result is None
+ # Should NOT print "ngrok not found" again after user declined
+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)
+ assert "ngrok not found" not in printed
+
+
+def test_offer_install_non_interactive() -> None:
+ """Non-interactive mode (--tunnel in CI) prints error and returns None without prompting."""
+ with patch("skyvern.cli.core.ngrok.console") as mock_console:
+ result = offer_install_ngrok(interactive=False)
+ assert result is None
+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)
+ assert "ngrok not found" in printed
+
+
+def test_offer_setup_auth_success() -> None:
+ with (
+ patch("skyvern.cli.core.ngrok.subprocess.run", return_value=subprocess.CompletedProcess(args=[], returncode=0)),
+ patch("skyvern.cli.core.ngrok.open_url"),
+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=True),
+ patch("skyvern.cli.core.ngrok.Prompt.ask", return_value="my-token"),
+ ):
+ assert offer_setup_auth("/usr/local/bin/ngrok") is True
+
+
+def test_offer_setup_auth_skipped() -> None:
+ with (
+ patch("skyvern.cli.core.ngrok.open_url"),
+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=False),
+ patch("skyvern.cli.core.ngrok.Prompt.ask", return_value=""),
+ ):
+ assert offer_setup_auth("/usr/local/bin/ngrok") is False
+
+
+def test_offer_setup_auth_non_interactive() -> None:
+ """Non-interactive mode prints instructions and returns False without prompting."""
+ with patch("skyvern.cli.core.ngrok.console") as mock_console:
+ result = offer_setup_auth("/usr/local/bin/ngrok", interactive=False)
+ assert result is False
+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)
+ assert "auth token not configured" in printed
+ assert "add-authtoken" in printed