Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

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.py
new file mode 100644
index 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.py
index 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 config
meta_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 flags
parser.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 provided
if args.api_key:
os.environ['BROWSER_USE_API_KEY'] = args.api_key
diff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.py
index 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.sh
index 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 bash
set -e
+# =============================================================================
+# Configuration
+# =============================================================================
+
+# Mode flags (set by parse_args or TUI)
+INSTALL_LOCAL=false
+INSTALL_REMOTE=false
+SKIP_INTERACTIVE=false
+API_KEY=""
+
# Colors for output
RED='\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 cloudflared
else
# Direct download for macOS without Homebrew
+ mkdir -p "$HOME/.local/bin"
if [ "$arch" = "arm64" ]; then
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz -o /tmp/cloudflared.tgz
else
@@ -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 venv
source "$HOME/.browser-use-env/bin/activate"
- # Parse profile from arguments
+ # Determine profile based on mode selections
local 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" --yes
else
- browser-use setup --profile "$profile"
+ browser-use setup --profile "$profile" --yes
fi
}
-# 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 platform
detect_platform
@@ -358,22 +607,35 @@ main() {
# Step 3: Install uv
install_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 PATH
configure_path
- # Step 7: Run setup wizard
- run_setup "$@"
+ # Step 8: Run setup wizard
+ run_setup
- # Step 8: Validate
+ # Step 9: Validate
validate
- # Step 9: Show next steps
+ # Step 10: Show next steps
print_next_steps
}
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index 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 session
browser-use state # Get page elements with indices
browser-use click 5 # Click element by index
browser-use type "Hello World" # Type into focused element
@@ -67,32 +78,15 @@ browser-use screenshot page.png # Save screenshot to file
browser-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.com
browser-use state
browser-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/contact
browser-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.com
for i in 1 2 3 4 5; do
browser-use scroll down
browser-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 retry
diff --git a/tests/ci/test_install_config.py b/tests/ci/test_install_config.py
new file mode 100644
index 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']