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
docs: migrate remote browser skill to CLI 3.0
MagMueller5525c08c54bb
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex 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.pyindex 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')