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
fix(cli): error when requesting remote browser on local session + improve docs
ShawnPana9f51461bbd19
diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex 96c0e4e87..9af7ee953 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -203,16 +203,22 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,meta = json.loads(meta_path.read_text())existing_mode = meta.get('browser_mode', 'chromium')if existing_mode != browser:- print(- f"Error: Session '{session}' is running with --browser {existing_mode}, "- f"but --browser {browser} was requested.\n\n"- f"Options:\n"- f" 1. Use existing browser: browser-use --browser {existing_mode} <command>\n"- f" 2. Use different session: browser-use --browser {browser} --session other <command>\n"- f" 3. Close existing session: browser-use close",- file=sys.stderr,- )- sys.exit(1)+ # Only error if user explicitly requested 'remote' but session is local+ # This prevents losing cloud features (live_url, etc.)+ # The reverse case (requesting local but having remote) is fine -+ # user still gets a working browser, just with more features+ 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>",+ file=sys.stderr,+ )+ sys.exit(1)except (json.JSONDecodeError, OSError):pass # Metadata file corrupt, ignorediff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex ada3f58ba..6d1b83d5d 100644--- a/skills/remote-browser/SKILL.md+++ b/skills/remote-browser/SKILL.md@@ -48,18 +48,51 @@ browser-use doctor## Core Workflow+**IMPORTANT: Use `--browser remote` on your FIRST command to create a cloud browser session.**+```bash-browser-use --browser remote open https://example.com # Open URL in cloud browser-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-browser-use input 3 "text" # Click element, then type-browser-use screenshot # Take screenshot (base64)-browser-use screenshot page.png # Save screenshot to file-browser-use close # Close browser+# Step 1: Start session with --browser remote (REQUIRED on first command)+browser-use --browser remote 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)+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+browser-use input 3 "text" # Click element, then type+browser-use screenshot # Take screenshot (base64)+browser-use screenshot page.png # Save screenshot to file++# Done: Close the session+browser-use close # Close browser and release resources```-The `open` command returns a `live_url` for cloud browsers — a real-time browser viewport you can view in any browser.+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 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>+```++**Fix:** Always close the session first, then start fresh with `--browser remote`.## Exposing Local Dev Servers@@ -220,15 +253,21 @@ done## Tips-1. **Always use `--browser remote`** on sandboxed machines (no local Chrome available)-2. **Always run `state` first** to see available elements and their indices-3. **Sessions persist** across commands — the browser stays open-4. **Use `--json`** for programmatic parsing-5. **`tunnel` is idempotent** — calling it again for the same port returns the existing URL-6. **Close when done** — `browser-use close` cleans up browser and tunnels+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. **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` cleans up browser and 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+**Cloud browser won't start?**- Verify `BROWSER_USE_API_KEY` is set- Check your API key at https://browser-use.comdiff --git a/tests/ci/test_session_browser_mode.py b/tests/ci/test_session_browser_mode.pyindex ea4d3ad42..0bc26ddf5 100644--- a/tests/ci/test_session_browser_mode.py+++ b/tests/ci/test_session_browser_mode.py@@ -82,21 +82,50 @@ def test_metadata_cleanup():assert not meta_path.exists()-def test_mode_mismatch_detection_logic():- """Test the mode mismatch detection logic directly."""- meta_path = get_session_metadata_path('test-mismatch')+def test_mode_mismatch_remote_on_local_should_error():+ """Test that requesting remote on local session triggers error condition.++ This is the problematic case: user wants cloud features (live_url) but+ session is running locally. They would silently lose those features.+ """+ meta_path = get_session_metadata_path('test-mismatch-error')try:- # Simulate existing session with chromium mode+ # Simulate existing session with chromium (local) modemeta_path.write_text(json.dumps({'browser_mode': 'chromium'}))- # Check mismatch detectionmeta = json.loads(meta_path.read_text())existing_mode = meta.get('browser_mode', 'chromium')requested_mode = 'remote'- assert existing_mode != requested_mode- assert existing_mode == 'chromium'- assert requested_mode == 'remote'+ # This combination should trigger an error+ should_error = requested_mode == 'remote' and existing_mode != 'remote'+ assert should_error is True+ finally:+ if meta_path.exists():+ meta_path.unlink()+++def test_mode_mismatch_local_on_remote_should_allow():+ """Test that requesting local on remote session is allowed.++ This case is fine: user gets a remote browser (more features than requested).+ The remote session works just like a local one, just with extra features.+ """+ meta_path = get_session_metadata_path('test-mismatch-allow')+ try:+ # Simulate existing session with remote mode+ meta_path.write_text(json.dumps({'browser_mode': 'remote'}))++ meta = json.loads(meta_path.read_text())+ existing_mode = meta.get('browser_mode')+ assert existing_mode == 'remote'++ requested_mode = 'chromium' # Default mode when user doesn't specify --browser++ # This combination should NOT trigger an error+ # (user requested chromium, but session is remote - that's fine)+ should_error = requested_mode == 'remote' and existing_mode != 'remote'+ assert should_error is Falsefinally:if meta_path.exists():meta_path.unlink()