Skip to content

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

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.py
index 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, ignore
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index 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.com
diff --git a/tests/ci/test_session_browser_mode.py b/tests/ci/test_session_browser_mode.py
index 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) mode
meta_path.write_text(json.dumps({'browser_mode': 'chromium'}))
- # Check mismatch detection
meta = 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 False
finally:
if meta_path.exists():
meta_path.unlink()