Skip to content

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

docs: migrate remote browser skill to CLI 3.0

MagMueller5525c08c54bb
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index 9c8b0efe9..7c0e52d6b 100644
--- a/skills/remote-browser/SKILL.md
+++ b/skills/remote-browser/SKILL.md
@@ -1,179 +1,91 @@
---
name: remote-browser
-description: Controls a local browser from a sandboxed remote machine. Use when the agent is running in a sandbox (no GUI) and needs to navigate websites, interact with web pages, fill forms, take screenshots, or expose local dev servers via tunnels.
+description: Controls an isolated Browser Use Cloud browser from a sandboxed machine with the current Browser Use CLI.
allowed-tools: Bash(browser-use:*)
---
-# Browser Automation for Sandboxed Agents
+# Remote Browser
-This skill is for agents running on **sandboxed remote machines** (cloud VMs, CI, coding agents) that need to control a headless browser.
+Use this skill when an agent runs on a machine without a usable local Chrome and needs an isolated browser. The current Browser Use CLI runs Python from stdin. Do not use the removed `open`, `state`, `click`, `input`, `tab`, `cloud connect`, or `--connect` commands.
-## Prerequisites
+## Check the CLI
```bash
-browser-use doctor # Verify installation
+browser-use --doctor
+browser-use skill show
```
-For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
+If setup fails, follow the current [Browser Use skill](../browser-use/SKILL.md).
-## Core Workflow
+## Start an isolated browser
-1. **Navigate**: `browser-use open <url>` — starts headless browser if needed
-2. **Inspect**: `browser-use state` — returns clickable elements with indices
-3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
-4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
-5. **Repeat**: browser stays open between commands
-6. **Cleanup**: `browser-use close` when done
-
-## Browser Modes
-
-```bash
-browser-use open <url> # Default: headless Chromium
-browser-use cloud connect # Provision cloud browser and connect
-browser-use --connect open <url> # Auto-discover running Chrome via CDP
-browser-use --cdp-url ws://localhost:9222/... open <url> # Connect via CDP URL
-```
-
-## Commands
+Authenticate once:
```bash
-# Navigation
-browser-use open <url> # Navigate to URL
-browser-use back # Go back in history
-browser-use scroll down # Scroll down (--amount N for pixels)
-browser-use scroll up # Scroll up
-browser-use tab list # List all tabs with lock status
-browser-use tab new [url] # Open a new tab (blank or with URL)
-browser-use tab switch <index> # Switch to tab by index
-browser-use tab close <index> [index...] # Close one or more tabs
-
-# Page State — always run state first to get element indices
-browser-use state # URL, title, clickable elements with indices
-browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page)
-
-# Interactions — use indices from state
-browser-use click <index> # Click element by index
-browser-use click <x> <y> # Click at pixel coordinates
-browser-use type "text" # Type into focused element
-browser-use input <index> "text" # Click element, then type
-browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.)
-browser-use select <index> "option" # Select dropdown option
-browser-use upload <index> <path> # Upload file to file input
-browser-use hover <index> # Hover over element
-browser-use dblclick <index> # Double-click element
-browser-use rightclick <index> # Right-click element
-
-# Data Extraction
-browser-use eval "js code" # Execute JavaScript, return result
-browser-use get title # Page title
-browser-use get html [--selector "h1"] # Page HTML (or scoped to selector)
-browser-use get text <index> # Element text content
-browser-use get value <index> # Input/textarea value
-browser-use get attributes <index> # Element attributes
-browser-use get bbox <index> # Bounding box (x, y, width, height)
-
-# Wait
-browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
-browser-use wait text "text" # Wait for text to appear
-
-# Cookies
-browser-use cookies get [--url <url>] # Get cookies (optionally filtered)
-browser-use cookies set <name> <value> # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
-browser-use cookies clear [--url <url>] # Clear cookies
-browser-use cookies export <file> # Export to JSON
-browser-use cookies import <file> # Import from JSON
-
-# Python — persistent session with browser access
-browser-use python "code" # Execute Python (variables persist across calls)
-browser-use python --file script.py # Run file
-browser-use python --vars # Show defined variables
-browser-use python --reset # Clear namespace
-
-# Session
-browser-use close # Close browser and stop daemon
-browser-use sessions # List active sessions
-browser-use close --all # Close all sessions
+browser-use auth login
```
-The Python `browser` object provides: `browser.url`, `browser.title`, `browser.html`, `browser.goto(url)`, `browser.back()`, `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)`, `browser.screenshot(path)`, `browser.scroll(direction, amount)`, `browser.wait(seconds)`.
-
-## Tunnels
-
-Expose local dev servers to the browser via Cloudflare tunnels.
+Pick a short unique name. `r7k2` below is only an example.
```bash
-browser-use tunnel <port> # Start tunnel (idempotent)
-browser-use tunnel list # Show active tunnels
-browser-use tunnel stop <port> # Stop tunnel
-browser-use tunnel stop --all # Stop all tunnels
+browser-use <<'PY'
+start_remote_daemon("r7k2")
+PY
```
-## Command Chaining
-
-Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
+Use the same name for every command in this browser:
```bash
-browser-use open https://example.com && browser-use state
-browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
+BU_NAME=r7k2 browser-use <<'PY'
+new_tab("https://example.com")
+wait_for_load()
+print(page_info())
+PY
```
-Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
+Each remote daemon is a separate Browser Use Cloud browser. Use a different name for each parallel task. Remote browsers can bill until they stop or time out.
-## Common Workflows
+## Inspect and interact
-### Exposing Local Dev Servers
+Helpers are pre-imported. Keep multi-step work in one heredoc when practical.
```bash
-python -m http.server 3000 & # Start dev server
-browser-use tunnel 3000 # → https://abc.trycloudflare.com
-browser-use open https://abc.trycloudflare.com # Browse the tunnel
-```
-
-Tunnels are independent of browser sessions and persist across `browser-use close`.
-
-## Multi-Agent (--connect mode)
-
-Multiple agents can share one browser via `--connect`. Each agent gets its own tab — other agents can't interfere.
+BU_NAME=r7k2 browser-use <<'PY'
+print(page_info())
+print(js("document.title"))
-**Setup**: Register once, then pass the index with every `--connect` command:
+fill_input('input[name="q"]', "browser automation")
+press_key("Enter")
+wait_for_load()
-```bash
-INDEX=$(browser-use register) # → prints "1"
-browser-use --connect $INDEX open <url> # Navigate in agent's own tab
-browser-use --connect $INDEX state # Get state from agent's tab
-browser-use --connect $INDEX click <element> # Click in agent's tab
+print(page_info())
+PY
```
-- **Tab locking**: When an agent mutates a tab (click, type, navigate), that tab is locked to it. Other agents get an error if they try to mutate the same tab.
-- **Read-only access**: `state`, `screenshot`, `get`, and `wait` commands work on any tab regardless of locks.
-- **Agent sessions expire** after 5 minutes of inactivity. Run `browser-use register` again to get a new index.
-
-## Global Options
+Useful helpers:
-| Option | Description |
-|--------|-------------|
-| `--headed` | Show browser window |
-| `--connect` | Auto-discover running Chrome via CDP |
-| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
-| `--session NAME` | Target a named session (default: "default") |
-| `--json` | Output as JSON |
+- Navigate: `new_tab(url)`, `goto_url(url)`, `wait_for_load()`
+- Inspect: `page_info()`, `js(code)`, `cdp(method, ...)`
+- Interact: `click_at_xy(x, y)`, `type_text(text)`, `fill_input(selector, text)`, `press_key(key)`, `scroll(x, y)`
+- Tabs: `list_tabs()`, `switch_tab(target)`, `close_tab(target)`
+- Files and proof: `capture_screenshot()`, `wait_for_element(selector)`
-## Tips
+Prefer the accessibility tree for element discovery:
-1. **Always run `state` first** to see available elements and their indices
-2. **Sessions persist** — browser stays open between commands until you close it
-3. **Tunnels are independent** — they persist across `browser-use close`
-4. **`tunnel` is idempotent** — calling again for the same port returns the existing URL
+```python
+nodes = cdp("Accessibility.getFullAXTree")["nodes"]
+```
-## Troubleshooting
+Use a targeted `js(...)` query when the accessibility tree lacks the element. Verify each action with `page_info()`, a focused DOM check, or a screenshot.
-- **Browser won't start?** `browser-use close` then retry. Run `browser-use doctor` to check.
-- **Element not found?** `browser-use scroll down` then `browser-use state`
-- **Tunnel not working?** `which cloudflared` to check, `browser-use tunnel list` to see active tunnels
+## Stop the browser
-## Cleanup
+When the work is done, stop the exact named browser:
```bash
-browser-use close # Close browser session
-browser-use tunnel stop --all # Stop tunnels (if any)
+browser-use <<'PY'
+stop_remote_daemon("r7k2")
+PY
```
+
+Do not leave an unused remote browser running.
diff --git a/tests/ci/test_browser_use_skill_install_docs.py b/tests/ci/test_browser_use_skill_install_docs.py
index 41da21a81..878e570a6 100644
--- a/tests/ci/test_browser_use_skill_install_docs.py
+++ b/tests/ci/test_browser_use_skill_install_docs.py
@@ -57,6 +57,32 @@ def test_docs_install_browser_use_skill_from_package_alias():
assert 'raw.githubusercontent.com/browser-use/browser-harness/main/SKILL.md' not in readme
+def test_remote_browser_skill_uses_current_cli():
+ remote_skill = (ROOT / 'skills' / 'remote-browser' / 'SKILL.md').read_text(encoding='utf-8')
+
+ for removed_command in (
+ 'browser-use open',
+ 'browser-use state',
+ 'browser-use click',
+ 'browser-use input',
+ 'browser-use tab',
+ 'browser-use cloud connect',
+ 'browser-use --connect',
+ 'browser_use/skill_cli/README.md',
+ ):
+ assert removed_command not in remote_skill
+
+ for current_command in (
+ "browser-use <<'PY'",
+ 'start_remote_daemon("r7k2")',
+ 'BU_NAME=r7k2 browser-use',
+ 'new_tab("https://example.com")',
+ 'print(page_info())',
+ 'stop_remote_daemon("r7k2")',
+ ):
+ assert current_command in remote_skill
+
+
def test_browser_use_cli_installs_browser_harness_package_skill(tmp_path):
bin_dir = _fake_browser_harness_tools(tmp_path, '---\nname: browser-harness\n---\n\n# Browser Harness\n')