remote-browser · diff
git:20260325.f819d3e to git:20260829.5525c08
49 added, 137 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
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
-
- ## Core Workflow
-
- 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
+ If setup fails, follow the current [Browser Use skill](../browser-use/SKILL.md).
- ```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
- ```
+ ## Start an isolated browser
- ## 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 "user@example.com" && 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.