Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
feat(install): mode-based installation with interactive TUI
ShawnPanac0dd7875b88e
diff --git a/browser_use/skill_cli/install_config.py b/browser_use/skill_cli/install_config.pynew file mode 100644index 000000000..03dfff7cb--- /dev/null+++ b/browser_use/skill_cli/install_config.py@@ -0,0 +1,111 @@+"""Install configuration - tracks which browser modes are available.++This module manages the installation configuration that determines which browser+modes (chromium, real, remote) are available based on how browser-use was installed.++Config file: ~/.browser-use/install-config.json++When no config file exists (e.g., pip install users), all modes are available by default.+"""++import json+from pathlib import Path+from typing import Literal++CONFIG_PATH = Path.home() / '.browser-use' / 'install-config.json'++ModeType = Literal['chromium', 'real', 'remote']++# Local modes (both require Chromium to be installed)+LOCAL_MODES: set[str] = {'chromium', 'real'}+++def get_config() -> dict:+ """Read install config. Returns default if not found.++ Default config enables all modes (for pip install users).+ """+ if not CONFIG_PATH.exists():+ return {+ 'installed_modes': ['chromium', 'real', 'remote'],+ 'default_mode': 'chromium',+ }++ try:+ return json.loads(CONFIG_PATH.read_text())+ except (json.JSONDecodeError, OSError):+ # Config file corrupt, return default+ return {+ 'installed_modes': ['chromium', 'real', 'remote'],+ 'default_mode': 'chromium',+ }+++def save_config(installed_modes: list[str], default_mode: str) -> None:+ """Save install config."""+ CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)+ CONFIG_PATH.write_text(+ json.dumps(+ {+ 'installed_modes': installed_modes,+ 'default_mode': default_mode,+ },+ indent=2,+ )+ )+++def is_mode_available(mode: str) -> bool:+ """Check if a browser mode is available based on installation config.++ Args:+ mode: The browser mode to check ('chromium', 'real', or 'remote')++ Returns:+ True if the mode is available, False otherwise+ """+ config = get_config()+ installed = config.get('installed_modes', [])++ # Map 'real' to same category as 'chromium' (both are local)+ # If either local mode is installed, both are available+ if mode in LOCAL_MODES:+ return bool(LOCAL_MODES & set(installed))++ return mode in installed+++def get_default_mode() -> str:+ """Get the default browser mode based on installation config."""+ return get_config().get('default_mode', 'chromium')+++def get_available_modes() -> list[str]:+ """Get list of available browser modes."""+ return get_config().get('installed_modes', ['chromium', 'real', 'remote'])+++def get_mode_unavailable_error(mode: str) -> str:+ """Generate a helpful error message when a mode is not available.++ Args:+ mode: The unavailable mode that was requested++ Returns:+ A formatted error message with instructions for reinstalling+ """+ available = get_available_modes()++ if mode in LOCAL_MODES:+ install_flag = '--full'+ mode_desc = 'Local browser mode'+ else:+ install_flag = '--full'+ mode_desc = 'Remote browser mode'++ return (+ f"Error: {mode_desc} '{mode}' not installed.\n"+ f'Available modes: {", ".join(available)}\n\n'+ f'To install all modes, reinstall with:\n'+ f' curl -fsSL https://browser-use.com/install.sh | bash -s -- {install_flag}'+ )diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex a97c3eb35..746dee39b 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -210,12 +210,12 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,if browser == 'remote' and existing_mode != 'remote':print(f"Error: Session '{session}' is running with --browser {existing_mode}, "- f"but --browser remote was requested.\n\n"- f"Cloud browser features (live_url) require a remote session.\n\n"- f"Options:\n"- f" 1. Close and restart: browser-use close && browser-use --browser remote open <url>\n"- f" 2. Use different session: browser-use --browser remote --session other <command>\n"- f" 3. Use existing local browser: browser-use --browser {existing_mode} <command>",+ f'but --browser remote was requested.\n\n'+ f'Cloud browser features (live_url) require a remote session.\n\n'+ f'Options:\n'+ f' 1. Close and restart: browser-use close && browser-use --browser remote open <url>\n'+ f' 2. Use different session: browser-use --browser remote --session other <command>\n'+ f' 3. Use existing local browser: browser-use --browser {existing_mode} <command>',file=sys.stderr,)sys.exit(1)@@ -275,11 +275,13 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,# Write metadata file to track session configmeta_path.write_text(- json.dumps({- 'browser_mode': browser,- 'headed': headed,- 'profile': profile,- })+ json.dumps(+ {+ 'browser_mode': browser,+ 'headed': headed,+ 'profile': profile,+ }+ ))return True@@ -328,6 +330,12 @@ def send_command(session: str, action: str, params: dict) -> dict:def build_parser() -> argparse.ArgumentParser:"""Build argument parser with all commands."""+ # Import install config to get available modes and default+ from browser_use.skill_cli.install_config import get_available_modes, get_default_mode++ available_modes = get_available_modes()+ default_mode = get_default_mode()+parser = argparse.ArgumentParser(prog='browser-use',description='Browser automation CLI for browser-use',@@ -350,7 +358,13 @@ Examples:# Global flagsparser.add_argument('--session', '-s', default='default', help='Session name (default: default)')- parser.add_argument('--browser', '-b', choices=['chromium', 'real', 'remote'], default='chromium', help='Browser mode')+ parser.add_argument(+ '--browser',+ '-b',+ choices=available_modes,+ default=default_mode,+ help=f'Browser mode (available: {", ".join(available_modes)})',+ )parser.add_argument('--headed', action='store_true', help='Show browser window')parser.add_argument('--profile', help='Chrome profile (real browser mode)')parser.add_argument('--json', action='store_true', help='Output as JSON')@@ -1261,7 +1275,7 @@ def main() -> int:if result.get('status') == 'success':print('\n✓ Setup complete!')print(f'\nProfile: {result["profile"]}')- print(f'Next: browser-use open https://example.com')+ print('Next: browser-use open https://example.com')return 0# Handle doctor command@@ -1336,6 +1350,13 @@ def main() -> int:print(f'Stopped tunnel on port {result["stopped"]}')return 0+ # Validate requested mode is available based on installation config+ from browser_use.skill_cli.install_config import get_mode_unavailable_error, is_mode_available++ if not is_mode_available(args.browser):+ print(get_mode_unavailable_error(args.browser), file=sys.stderr)+ return 1+# Set API key in environment if providedif args.api_key:os.environ['BROWSER_USE_API_KEY'] = args.api_keydiff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.pyindex 6b94311b9..4c4762026 100644--- a/browser_use/skill_cli/sessions.py+++ b/browser_use/skill_cli/sessions.py@@ -119,7 +119,16 @@ async def create_browser_session(- chromium: Playwright-managed Chromium (default)- real: User's Chrome with profile- remote: Browser-Use Cloud (requires API key)++ Raises:+ RuntimeError: If the requested mode is not available based on installation config"""+ from browser_use.skill_cli.install_config import get_mode_unavailable_error, is_mode_available++ # Validate mode is available based on installation config+ if not is_mode_available(mode):+ raise RuntimeError(get_mode_unavailable_error(mode))+if mode == 'chromium':return BrowserSession(headless=not headed,diff --git a/install.sh b/install.shindex 5fa1834a7..76c71e5bf 100755--- a/install.sh+++ b/install.sh@@ -1,29 +1,45 @@#!/usr/bin/env bash-# Browser-Use Bootstrap Installer (DEV TESTING)-#-# NOTE: This script is for development testing only. Production version will-# install from PyPI. For now, use BROWSER_USE_BRANCH to install from GitHub.+# Browser-Use Bootstrap Installer## Usage:-# # Install from GitHub branch (for testing)-# curl -fsSL <raw-url> | BROWSER_USE_BRANCH=frictionless-install bash+# # Interactive install (shows mode selection TUI)+# curl -fsSL https://browser-use.com/install.sh | bash#-# # With profile-# curl -fsSL <raw-url> | BROWSER_USE_BRANCH=frictionless-install bash -s -- --profile remote+# # Non-interactive install with flags+# curl -fsSL https://browser-use.com/install.sh | bash -s -- --full+# curl -fsSL https://browser-use.com/install.sh | bash -s -- --remote-only+# curl -fsSL https://browser-use.com/install.sh | bash -s -- --local-only#-# Once released, production usage will be:-# curl -fsSL https://browser-use.com/install.sh | bash+# # With API key+# curl -fsSL https://browser-use.com/install.sh | bash -s -- --remote-only --api-key bu_xxx+#+# For development testing:+# curl -fsSL <raw-url> | BROWSER_USE_BRANCH=frictionless-install bashset -e+# =============================================================================+# Configuration+# =============================================================================++# Mode flags (set by parse_args or TUI)+INSTALL_LOCAL=false+INSTALL_REMOTE=false+SKIP_INTERACTIVE=false+API_KEY=""+# Colors for outputRED='\033[0;31m'GREEN='\033[0;32m'YELLOW='\033[1;33m'BLUE='\033[0;34m'+BOLD='\033[1m'NC='\033[0m' # No Color+# =============================================================================# Logging functions+# =============================================================================+log_info() {echo -e "${BLUE}ℹ${NC} $1"}@@ -40,7 +56,59 @@ log_error() {echo -e "${RED}✗${NC} $1"}-# Detect platform+# =============================================================================+# Argument parsing+# =============================================================================++parse_args() {+ while [[ $# -gt 0 ]]; do+ case $1 in+ --full|--all)+ INSTALL_LOCAL=true+ INSTALL_REMOTE=true+ SKIP_INTERACTIVE=true+ shift+ ;;+ --remote-only)+ INSTALL_REMOTE=true+ SKIP_INTERACTIVE=true+ shift+ ;;+ --local-only)+ INSTALL_LOCAL=true+ SKIP_INTERACTIVE=true+ shift+ ;;+ --api-key)+ API_KEY="$2"+ shift 2+ ;;+ --help|-h)+ echo "Browser-Use Installer"+ echo ""+ echo "Usage: install.sh [OPTIONS]"+ echo ""+ echo "Options:"+ echo " --full, --all Install all modes (local + remote)"+ echo " --remote-only Install remote mode only (no Chromium)"+ echo " --local-only Install local modes only (no cloudflared)"+ echo " --api-key KEY Set Browser-Use API key"+ echo " --help, -h Show this help"+ echo ""+ echo "Without options, shows interactive mode selection."+ exit 0+ ;;+ *)+ shift+ ;;+ esac+ done+}++# =============================================================================+# Platform detection+# =============================================================================+detect_platform() {local os=$(uname -s | tr '[:upper:]' '[:lower:]')local arch=$(uname -m)@@ -64,7 +132,10 @@ detect_platform() {log_info "Detected platform: $PLATFORM ($arch)"}-# Check Python version+# =============================================================================+# Python management+# =============================================================================+check_python() {log_info "Checking Python installation..."@@ -92,7 +163,6 @@ check_python() {fi}-# Install Python (platform-specific)install_python() {log_info "Installing Python 3.11+..."@@ -131,7 +201,10 @@ install_python() {fi}-# Install uv package manager+# =============================================================================+# uv package manager+# =============================================================================+install_uv() {log_info "Installing uv package manager..."@@ -154,7 +227,69 @@ install_uv() {fi}-# Install browser-use+# =============================================================================+# Interactive mode selection TUI+# =============================================================================++show_mode_menu() {+ # Check for TUI tools in order of preference+ if command -v gum &> /dev/null; then+ show_gum_menu+ elif command -v whiptail &> /dev/null; then+ show_whiptail_menu+ else+ show_bash_menu+ fi+}++show_gum_menu() {+ echo ""+ echo "Select browser modes to install:"+ echo ""++ SELECTED=$(gum choose --no-limit --height 10 \+ "Local browser (chromium/real - requires Chromium download)" \+ "Remote browser (cloud - requires API key)")++ # Parse selections+ [[ "$SELECTED" == *"Local"* ]] && INSTALL_LOCAL=true+ [[ "$SELECTED" == *"Remote"* ]] && INSTALL_REMOTE=true+}++show_whiptail_menu() {+ # Use whiptail for interactive menu+ local result=$(whiptail --title "Browser-Use Installer" \+ --checklist "Select browser modes to install:" 12 60 2 \+ "local" "Local browser (chromium/real)" ON \+ "remote" "Remote browser (cloud)" OFF \+ 3>&1 1>&2 2>&3) || true++ [[ "$result" == *"local"* ]] && INSTALL_LOCAL=true+ [[ "$result" == *"remote"* ]] && INSTALL_REMOTE=true+}++show_bash_menu() {+ echo ""+ echo "Select browser modes to install (space-separated numbers):"+ echo ""+ echo " 1) Local browser (chromium/real - requires Chromium download)"+ echo " 2) Remote browser (cloud - requires API key)"+ echo ""+ echo "Press Enter for default [1]"+ echo ""++ # Read with timeout and default+ read -t 60 -p "> " choices || choices="1"+ choices=${choices:-1}++ [[ "$choices" == *"1"* ]] && INSTALL_LOCAL=true+ [[ "$choices" == *"2"* ]] && INSTALL_REMOTE=true+}++# =============================================================================+# Browser-Use installation+# =============================================================================+install_browser_use() {log_info "Installing browser-use..."@@ -182,7 +317,23 @@ install_browser_use() {log_success "browser-use installed"}-# Install cloudflared for tunneling+install_chromium() {+ log_info "Installing Chromium browser..."++ source "$HOME/.browser-use-env/bin/activate"++ # Build command - only use --with-deps on Linux (it fails on Windows/macOS)+ local cmd="uvx playwright install chromium"+ if [ "$PLATFORM" = "linux" ]; then+ cmd="$cmd --with-deps"+ fi+ cmd="$cmd --no-shell"++ eval $cmd++ log_success "Chromium installed"+}+install_cloudflared() {log_info "Installing cloudflared..."@@ -199,6 +350,7 @@ install_cloudflared() {brew install cloudflaredelse# Direct download for macOS without Homebrew+ mkdir -p "$HOME/.local/bin"if [ "$arch" = "arm64" ]; thencurl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz -o /tmp/cloudflared.tgzelse@@ -233,7 +385,66 @@ install_cloudflared() {fi}-# Add to PATH permanently+# =============================================================================+# Install dependencies based on selected modes+# =============================================================================++install_dependencies() {+ # Install base package (always needed)+ install_browser_use++ # Install Chromium only if local mode selected+ if [ "$INSTALL_LOCAL" = true ]; then+ install_chromium+ else+ log_info "Skipping Chromium (remote-only mode)"+ fi++ # Install cloudflared only if remote mode selected+ if [ "$INSTALL_REMOTE" = true ]; then+ install_cloudflared+ else+ log_info "Skipping cloudflared (local-only mode)"+ fi+}++# =============================================================================+# Write install configuration+# =============================================================================++write_install_config() {+ # Determine installed modes and default+ local modes=""+ local default_mode=""++ if [ "$INSTALL_LOCAL" = true ] && [ "$INSTALL_REMOTE" = true ]; then+ modes='["chromium", "real", "remote"]'+ default_mode="chromium"+ elif [ "$INSTALL_REMOTE" = true ]; then+ modes='["remote"]'+ default_mode="remote"+ else+ modes='["chromium", "real"]'+ default_mode="chromium"+ fi++ # Write config file+ mkdir -p "$HOME/.browser-use"+ cat > "$HOME/.browser-use/install-config.json" << EOF+{+ "installed_modes": $modes,+ "default_mode": "$default_mode"+}+EOF++ local mode_names=$(echo $modes | tr -d '[]"' | tr ',' ' ')+ log_success "Configured: $mode_names"+}++# =============================================================================+# PATH configuration+# =============================================================================+configure_path() {local shell_rc=""local bin_path="$HOME/.browser-use-env/bin"@@ -260,47 +471,38 @@ configure_path() {echo "export PATH=\"$bin_path:$local_bin:\$PATH\"" >> "$shell_rc"log_success "Added to PATH in $shell_rc"- log_warn "Restart your shell or run: source $shell_rc"}-# Run setup wizard+# =============================================================================+# Setup wizard+# =============================================================================+run_setup() {log_info "Running setup wizard..."# Activate venvsource "$HOME/.browser-use-env/bin/activate"- # Parse profile from arguments+ # Determine profile based on mode selectionslocal profile="local"- while [[ $# -gt 0 ]]; do- case $1 in- --profile)- profile="$2"- shift 2- ;;- *)- shift- ;;- esac- done-- # Run setup- if [ "$profile" = "remote" ] || [ "$profile" = "full" ]; then- log_info "Setup requires API key for $profile profile"- read -p "Enter Browser-Use API key (or leave empty to skip): " api_key+ if [ "$INSTALL_REMOTE" = true ] && [ "$INSTALL_LOCAL" = true ]; then+ profile="full"+ elif [ "$INSTALL_REMOTE" = true ]; then+ profile="remote"+ fi- if [ -n "$api_key" ]; then- browser-use setup --profile "$profile" --api-key "$api_key"- else- log_warn "Skipping API key configuration"- browser-use setup --profile local- fi+ # Run setup with API key if provided+ if [ -n "$API_KEY" ]; then+ browser-use setup --profile "$profile" --api-key "$API_KEY" --yeselse- browser-use setup --profile "$profile"+ browser-use setup --profile "$profile" --yesfi}-# Validate installation+# =============================================================================+# Validation+# =============================================================================+validate() {log_info "Validating installation..."@@ -315,24 +517,56 @@ validate() {fi}-# Print next steps+# =============================================================================+# Print completion message+# =============================================================================+print_next_steps() {+ # Detect shell for source command+ local shell_rc=".bashrc"+ if [ -n "$ZSH_VERSION" ]; then+ shell_rc=".zshrc"+ fi+echo ""echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"echo ""log_success "Browser-Use installed successfully!"echo ""+ echo "Installed modes:"+ [ "$INSTALL_LOCAL" = true ] && echo " ✓ Local (chromium, real)"+ [ "$INSTALL_REMOTE" = true ] && echo " ✓ Remote (cloud)"+ echo ""++ # Show API key instructions if remote selected but no key provided+ if [ "$INSTALL_REMOTE" = true ] && [ -z "$API_KEY" ]; then+ echo "⚠ API key required for remote mode:"+ echo " export BROWSER_USE_API_KEY=<your-api-key>"+ echo ""+ echo " Get your API key at: https://browser-use.com"+ echo ""+ fi+echo "Next steps:"- echo " 1. Restart your shell or run: source ~/.bashrc"- echo " 2. Try: browser-use open https://example.com"- echo " 3. For help: browser-use --help"+ echo " 1. Restart your shell or run: source ~/$shell_rc"++ if [ "$INSTALL_REMOTE" = true ] && [ -z "$API_KEY" ]; then+ echo " 2. Set your API key (see above)"+ echo " 3. Try: browser-use open https://example.com"+ else+ echo " 2. Try: browser-use open https://example.com"+ fi+echo ""echo "Documentation: https://docs.browser-use.com"echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"echo ""}+# =============================================================================# Main installation flow+# =============================================================================+main() {echo ""echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"@@ -340,6 +574,21 @@ main() {echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"echo ""+ # Parse command-line flags+ parse_args "$@"++ # Show install mode if flags provided+ if [ "$SKIP_INTERACTIVE" = true ]; then+ if [ "$INSTALL_LOCAL" = true ] && [ "$INSTALL_REMOTE" = true ]; then+ log_info "Install mode: full (local + remote)"+ elif [ "$INSTALL_REMOTE" = true ]; then+ log_info "Install mode: remote-only"+ else+ log_info "Install mode: local-only"+ fi+ echo ""+ fi+# Step 1: Detect platformdetect_platform@@ -358,22 +607,35 @@ main() {# Step 3: Install uvinstall_uv- # Step 4: Install browser-use- install_browser_use+ # Step 4: Show mode selection TUI (unless skipped via flags)+ if [ "$SKIP_INTERACTIVE" = false ]; then+ show_mode_menu+ fi++ # Default to local-only if nothing selected+ if [ "$INSTALL_LOCAL" = false ] && [ "$INSTALL_REMOTE" = false ]; then+ log_warn "No modes selected, defaulting to local"+ INSTALL_LOCAL=true+ fi++ echo ""++ # Step 5: Install dependencies+ install_dependencies- # Step 5: Install cloudflared (for tunneling)- install_cloudflared+ # Step 6: Write install config+ write_install_config- # Step 6: Configure PATH+ # Step 7: Configure PATHconfigure_path- # Step 7: Run setup wizard- run_setup "$@"+ # Step 8: Run setup wizard+ run_setup- # Step 8: Validate+ # Step 9: Validatevalidate- # Step 9: Show next steps+ # Step 10: Show next stepsprint_next_steps}diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex f59a9a618..0001041c0 100644--- a/skills/remote-browser/SKILL.md+++ b/skills/remote-browser/SKILL.md@@ -10,22 +10,33 @@ This skill is for agents running on **sandboxed remote machines** (cloud VMs, CI## Setup-**Option 1: One-command install (recommended)**+**Remote-only install (recommended for sandboxed agents)**```bash-curl -fsSL https://raw.githubusercontent.com/ShawnPana/browser-use/frictionless-install/install.sh | BROWSER_USE_BRANCH=frictionless-install bash+curl -fsSL https://browser-use.com/install.sh | bash -s -- --remote-only```-This installs Python, uv, browser-use CLI, cloudflared (for tunneling), and validates the setup automatically.+This configures browser-use to only use cloud browsers:+- No Chromium download (~300MB saved)+- `browser-use open <url>` automatically uses remote mode (no `--browser` flag needed)+- If API key is available, you can also pass it during install:+ ```bash+ curl -fsSL https://browser-use.com/install.sh | bash -s -- --remote-only --api-key bu_xxx+ ```-**Option 2: Manual install**+**For development testing (from GitHub branch):**```bash-# For dev testing (from this branch):-pip install "git+https://github.com/ShawnPana/browser-use@frictionless-install"+curl -fsSL https://raw.githubusercontent.com/ShawnPana/browser-use/frictionless-install/install.sh | BROWSER_USE_BRANCH=frictionless-install bash -s -- --remote-only+```-# For production (once released):-# pip install "browser-use[cli]"+**Manual install (alternative)**+```bash+# Install from PyPI (once released):+pip install "browser-use[cli]"++# Or from this branch for dev testing:+pip install "git+https://github.com/ShawnPana/browser-use@frictionless-install"-# Install cloudflared for tunneling (required for browser-use tunnel command):+# Install cloudflared for tunneling:# macOS:brew install cloudflared@@ -48,14 +59,14 @@ browser-use doctor## Core Workflow-**IMPORTANT: Use `--browser remote` on your FIRST command to create a cloud browser session.**+When installed with `--remote-only`, commands automatically use the cloud browser — no `--browser` flag needed:```bash-# Step 1: Start session with --browser remote (REQUIRED on first command)-browser-use --browser remote open https://example.com+# Step 1: Start session (automatically uses remote mode)+browser-use open https://example.com# Returns: url, live_url (view the browser in real-time)-# Step 2+: All subsequent commands use the existing session (no flag needed)+# Step 2+: All subsequent commands use the existing sessionbrowser-use state # Get page elements with indicesbrowser-use click 5 # Click element by indexbrowser-use type "Hello World" # Type into focused element@@ -67,32 +78,15 @@ browser-use screenshot page.png # Save screenshot to filebrowser-use close # Close browser and release resources```-The `--browser remote` flag only matters on the **first command** that creates the session. After that, all commands automatically use the existing cloud browser.+### Understanding Installation Modes-### Understanding Session Modes--| First Command | Session Type | Subsequent Commands |-|---------------|--------------|---------------------|-| `browser-use --browser remote open <url>` | Cloud browser | No flag needed |-| `browser-use open <url>` | Local browser | No flag needed |--### What Happens If You Forget `--browser remote`?--```bash-# WRONG: Starting without --browser remote creates a LOCAL session-browser-use open https://example.com # Creates LOCAL session (no live_url!)--# Then trying to switch to remote will ERROR:-browser-use --browser remote open https://other.com-# Error: Session 'default' is running with --browser chromium,-# but --browser remote was requested.-#-# Options:-# 1. Close and restart: browser-use close && browser-use --browser remote open <url>-# 2. Use different session: browser-use --browser remote --session other <command>-```+| Install Command | Available Modes | Default Mode | Use Case |+|-----------------|-----------------|--------------|----------|+| `--remote-only` | remote | remote | Sandboxed agents, no GUI |+| `--local-only` | chromium, real | chromium | Local development |+| `--full` | chromium, real, remote | chromium | Full flexibility |-**Fix:** Always close the session first, then start fresh with `--browser remote`.+When only one mode is installed, it becomes the default and no `--browser` flag is needed.## Exposing Local Dev Servers@@ -107,7 +101,7 @@ browser-use tunnel 3000# → url: https://abc.trycloudflare.com# Now the cloud browser can reach your local server-browser-use --browser remote open https://abc.trycloudflare.com+browser-use open https://abc.trycloudflare.com```Tunnel commands:@@ -121,7 +115,7 @@ browser-use tunnel stop --all # Stop all tunnels**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately.-Cloudflared is installed by `install.sh`. If missing, install manually (see Setup section).+Cloudflared is installed by `install.sh --remote-only`. If missing, install manually (see Setup section).## Commands@@ -207,7 +201,7 @@ browser-use close --all # Close all sessions| Option | Description ||--------|-------------|| `--session NAME` | Named session (default: "default") |-| `--browser remote` | Cloud browser (always use this on sandboxed machines) |+| `--browser MODE` | Browser mode (only if multiple modes installed) || `--profile ID` | Cloud profile ID for persistent cookies || `--json` | Output as JSON || `--api-key KEY` | Override API key |@@ -225,7 +219,7 @@ browser-use tunnel 3000# → url: https://abc.trycloudflare.com# Browse with cloud browser-browser-use --browser remote open https://abc.trycloudflare.com+browser-use open https://abc.trycloudflare.combrowser-use statebrowser-use screenshot```@@ -233,7 +227,7 @@ browser-use screenshot### Form Submission```bash-browser-use --browser remote open https://example.com/contact+browser-use open https://example.com/contactbrowser-use state# Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"browser-use input 0 "John Doe"@@ -246,7 +240,7 @@ browser-use state # Verify success### Screenshot Loop for Visual Verification```bash-browser-use --browser remote open https://example.com+browser-use open https://example.comfor i in 1 2 3 4 5; dobrowser-use scroll downbrowser-use screenshot "page_$i.png"@@ -255,21 +249,20 @@ done## Tips-1. **Use `--browser remote` on your FIRST command** — this creates a cloud browser session. Subsequent commands don't need the flag.-2. **Don't mix modes** — if you started with local, close first before switching to remote-3. **Always run `state` first** to see available elements and their indices-4. **Sessions persist** across commands — the browser stays open until you close it-5. **Tunnels are independent** — they don't require or create a browser session, and persist across `browser-use close`-6. **Use `--json`** for programmatic parsing-7. **`tunnel` is idempotent** — calling it again for the same port returns the existing URL-8. **Close when done** — `browser-use close` closes the browser; `browser-use tunnel stop --all` stops tunnels+1. **Install with `--remote-only`** for sandboxed environments — no `--browser` flag needed+2. **Always run `state` first** to see available elements and their indices+3. **Sessions persist** across commands — the browser stays open until you close it+4. **Tunnels are independent** — they don't require or create a browser session, and persist across `browser-use close`+5. **Use `--json`** for programmatic parsing+6. **`tunnel` is idempotent** — calling it again for the same port returns the existing URL+7. **Close when done** — `browser-use close` closes the browser; `browser-use tunnel stop --all` stops tunnels## Troubleshooting-**"Session is running with --browser chromium but --browser remote was requested"?**-- You started a local session and then tried to use `--browser remote`-- Fix: `browser-use close` then restart with `browser-use --browser remote open <url>`-- Prevention: Always use `--browser remote` on your first command+**"Browser mode 'chromium' not installed"?**+- You installed with `--remote-only` which doesn't include local modes+- This is expected behavior for sandboxed agents+- If you need local browser, reinstall with `--full`**Cloud browser won't start?**- Verify `BROWSER_USE_API_KEY` is set@@ -277,7 +270,7 @@ done**Tunnel not working?**- Verify cloudflared is installed: `which cloudflared`-- If missing, install manually (see Setup section) or re-run `install.sh`+- If missing, install manually (see Setup section) or re-run `install.sh --remote-only`- `browser-use tunnel list` to check active tunnels- `browser-use tunnel stop <port>` and retrydiff --git a/tests/ci/test_install_config.py b/tests/ci/test_install_config.pynew file mode 100644index 000000000..9c86883de--- /dev/null+++ b/tests/ci/test_install_config.py@@ -0,0 +1,182 @@+"""Tests for install configuration module."""++import json+import tempfile+from pathlib import Path+from unittest.mock import patch++import pytest+++class TestInstallConfig:+ """Tests for browser_use.skill_cli.install_config module."""++ @pytest.fixture+ def temp_config_dir(self, tmp_path: Path):+ """Create a temporary config directory and patch CONFIG_PATH."""+ config_path = tmp_path / 'install-config.json'+ with patch('browser_use.skill_cli.install_config.CONFIG_PATH', config_path):+ yield config_path++ def test_get_config_default_all_modes(self, temp_config_dir: Path):+ """If no config file, all modes available (pip install users)."""+ from browser_use.skill_cli.install_config import get_config++ # Config file doesn't exist+ assert not temp_config_dir.exists()++ config = get_config()+ assert config['installed_modes'] == ['chromium', 'real', 'remote']+ assert config['default_mode'] == 'chromium'++ def test_get_config_reads_existing_file(self, temp_config_dir: Path):+ """Config is read from existing file."""+ from browser_use.skill_cli.install_config import get_config++ # Create config file with remote-only mode+ temp_config_dir.parent.mkdir(parents=True, exist_ok=True)+ temp_config_dir.write_text(+ json.dumps({'installed_modes': ['remote'], 'default_mode': 'remote'})+ )++ config = get_config()+ assert config['installed_modes'] == ['remote']+ assert config['default_mode'] == 'remote'++ def test_get_config_handles_corrupt_file(self, temp_config_dir: Path):+ """Corrupt config file returns default."""+ from browser_use.skill_cli.install_config import get_config++ # Create corrupt config file+ temp_config_dir.parent.mkdir(parents=True, exist_ok=True)+ temp_config_dir.write_text('not valid json {{{')++ config = get_config()+ # Should return default+ assert config['installed_modes'] == ['chromium', 'real', 'remote']+ assert config['default_mode'] == 'chromium'++ def test_save_config_creates_file(self, temp_config_dir: Path):+ """save_config creates the config file."""+ from browser_use.skill_cli.install_config import save_config++ assert not temp_config_dir.exists()++ save_config(['remote'], 'remote')++ assert temp_config_dir.exists()+ config = json.loads(temp_config_dir.read_text())+ assert config['installed_modes'] == ['remote']+ assert config['default_mode'] == 'remote'++ def test_save_config_creates_parent_directories(self, tmp_path: Path):+ """save_config creates parent directories if needed."""+ from browser_use.skill_cli.install_config import save_config++ nested_path = tmp_path / 'deep' / 'nested' / 'install-config.json'+ with patch('browser_use.skill_cli.install_config.CONFIG_PATH', nested_path):+ save_config(['chromium', 'real'], 'chromium')++ assert nested_path.exists()++ def test_is_mode_available_remote_only(self, temp_config_dir: Path):+ """Config with only remote mode blocks local modes."""+ from browser_use.skill_cli.install_config import is_mode_available, save_config++ save_config(['remote'], 'remote')++ assert is_mode_available('remote') is True+ assert is_mode_available('chromium') is False+ assert is_mode_available('real') is False++ def test_is_mode_available_local_only(self, temp_config_dir: Path):+ """Config with only local modes blocks remote mode."""+ from browser_use.skill_cli.install_config import is_mode_available, save_config++ save_config(['chromium', 'real'], 'chromium')++ assert is_mode_available('chromium') is True+ assert is_mode_available('real') is True+ assert is_mode_available('remote') is False++ def test_is_mode_available_full_install(self, temp_config_dir: Path):+ """Config with all modes allows everything."""+ from browser_use.skill_cli.install_config import is_mode_available, save_config++ save_config(['chromium', 'real', 'remote'], 'chromium')++ assert is_mode_available('chromium') is True+ assert is_mode_available('real') is True+ assert is_mode_available('remote') is True++ def test_is_mode_available_local_modes_linked(self, temp_config_dir: Path):+ """If chromium is installed, real is also available (and vice versa)."""+ from browser_use.skill_cli.install_config import is_mode_available, save_config++ # Only chromium in the list, but real should also work+ save_config(['chromium'], 'chromium')++ assert is_mode_available('chromium') is True+ assert is_mode_available('real') is True # Linked to chromium++ # Only real in the list+ save_config(['real'], 'real')++ assert is_mode_available('chromium') is True # Linked to real+ assert is_mode_available('real') is True++ def test_get_default_mode(self, temp_config_dir: Path):+ """Default --browser value comes from config."""+ from browser_use.skill_cli.install_config import get_default_mode, save_config++ # Remote-only install+ save_config(['remote'], 'remote')+ assert get_default_mode() == 'remote'++ # Local-only install+ save_config(['chromium', 'real'], 'chromium')+ assert get_default_mode() == 'chromium'++ def test_get_available_modes(self, temp_config_dir: Path):+ """get_available_modes returns list from config."""+ from browser_use.skill_cli.install_config import get_available_modes, save_config++ save_config(['remote'], 'remote')+ assert get_available_modes() == ['remote']++ save_config(['chromium', 'real', 'remote'], 'chromium')+ assert get_available_modes() == ['chromium', 'real', 'remote']++ def test_get_mode_unavailable_error_message(self, temp_config_dir: Path):+ """Clear error when requesting unavailable mode."""+ from browser_use.skill_cli.install_config import get_mode_unavailable_error, save_config++ save_config(['remote'], 'remote')++ error = get_mode_unavailable_error('chromium')+ assert 'chromium' in error+ assert 'not installed' in error.lower()+ assert 'remote' in error # Shows available modes+ assert '--full' in error # Shows reinstall instructions++ def test_no_config_file_means_all_modes_available(self, temp_config_dir: Path):+ """pip install users (no config file) have all modes available."""+ from browser_use.skill_cli.install_config import (+ get_available_modes,+ get_default_mode,+ is_mode_available,+ )++ # Ensure no config exists+ assert not temp_config_dir.exists()++ # All modes should be available+ assert is_mode_available('chromium') is True+ assert is_mode_available('real') is True+ assert is_mode_available('remote') is True++ # Default should be chromium+ assert get_default_mode() == 'chromium'++ # All modes should be in the list+ assert get_available_modes() == ['chromium', 'real', 'remote']