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
Add `bu tunnel` command and remote-browser skill
Gregor Žunič9d7a0c74ed12
diff --git a/browser_use/skill_cli/commands/__init__.py b/browser_use/skill_cli/commands/__init__.pyindex c1208e027..775ed7dd2 100644--- a/browser_use/skill_cli/commands/__init__.py+++ b/browser_use/skill_cli/commands/__init__.py@@ -1,5 +1,5 @@"""Command handlers for browser-use CLI."""-from browser_use.skill_cli.commands import agent, browser, python_exec, session+from browser_use.skill_cli.commands import agent, browser, python_exec, session, tunnel-__all__ = ['browser', 'python_exec', 'agent', 'session']+__all__ = ['browser', 'python_exec', 'agent', 'session', 'tunnel']diff --git a/browser_use/skill_cli/commands/tunnel.py b/browser_use/skill_cli/commands/tunnel.pynew file mode 100644index 000000000..2572bcd40--- /dev/null+++ b/browser_use/skill_cli/commands/tunnel.py@@ -0,0 +1,122 @@+"""Tunnel commands - expose localhost ports via Cloudflare quick tunnels."""++import asyncio+import logging+import re+import shutil+from typing import Any++from browser_use.skill_cli.sessions import SessionInfo++logger = logging.getLogger(__name__)++COMMANDS = {'tunnel'}++_URL_PATTERN = re.compile(r'(https://\S+\.trycloudflare\.com)')+++async def handle(action: str, session_info: SessionInfo, params: dict[str, Any]) -> Any:+ """Handle tunnel command."""+ subcommand = params.get('subcommand', 'start')++ if subcommand == 'list':+ return list_tunnels(session_info)+ elif subcommand == 'stop':+ port = params.get('port')+ if port is None:+ return {'error': 'port is required for tunnel stop'}+ return await stop_tunnel(session_info, int(port))+ else:+ # Default: start+ port = params.get('port')+ if port is None:+ return {'error': 'port is required for tunnel start'}+ return await start_tunnel(session_info, int(port))+++async def start_tunnel(session_info: SessionInfo, port: int) -> dict[str, Any]:+ """Start a cloudflare quick tunnel for a local port."""+ # Check if tunnel already exists for this port+ if port in session_info.tunnels:+ info = session_info.tunnels[port]+ return {'url': info.url, 'port': port, 'existing': True}++ # Check cloudflared binary+ if not shutil.which('cloudflared'):+ return {+ 'error': 'cloudflared not found. Install it:\n'+ ' macOS: brew install cloudflared\n'+ ' Linux: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/\n'+ ' Windows: winget install Cloudflare.cloudflared',+ }++ # Spawn cloudflared process+ process = await asyncio.create_subprocess_exec(+ 'cloudflared',+ 'tunnel',+ '--url',+ f'http://localhost:{port}',+ stdout=asyncio.subprocess.DEVNULL,+ stderr=asyncio.subprocess.PIPE,+ )++ # Read stderr lines until we find the tunnel URL+ assert process.stderr is not None+ url: str | None = None+ try:+ deadline = asyncio.get_event_loop().time() + 15+ while asyncio.get_event_loop().time() < deadline:+ try:+ line_bytes = await asyncio.wait_for(process.stderr.readline(), timeout=1.0)+ except TimeoutError:+ continue+ if not line_bytes:+ break+ line = line_bytes.decode(errors='replace')+ match = _URL_PATTERN.search(line)+ if match:+ url = match.group(1)+ break+ except Exception as e:+ process.terminate()+ return {'error': f'Failed to start tunnel: {e}'}++ if url is None:+ process.terminate()+ return {'error': 'Timed out waiting for cloudflare tunnel URL (15s)'}++ # Store tunnel info+ from browser_use.skill_cli.sessions import TunnelInfo++ session_info.tunnels[port] = TunnelInfo(port=port, url=url, process=process)+ logger.info(f'Tunnel started: localhost:{port} -> {url}')++ return {'url': url, 'port': port}+++def list_tunnels(session_info: SessionInfo) -> dict[str, Any]:+ """List active tunnels."""+ tunnels = [{'port': info.port, 'url': info.url} for info in session_info.tunnels.values()]+ return {'tunnels': tunnels, 'count': len(tunnels)}+++async def stop_tunnel(session_info: SessionInfo, port: int) -> dict[str, Any]:+ """Stop a tunnel for a specific port."""+ if port not in session_info.tunnels:+ return {'error': f'No tunnel running on port {port}'}++ info = session_info.tunnels.pop(port)+ info.process.terminate()+ try:+ await asyncio.wait_for(info.process.wait(), timeout=5)+ except TimeoutError:+ info.process.kill()+ logger.info(f'Tunnel stopped: localhost:{port}')++ return {'stopped': port, 'url': info.url}+++async def stop_all_tunnels(session_info: SessionInfo) -> None:+ """Stop all tunnels. Called during session cleanup."""+ for port in list(session_info.tunnels.keys()):+ await stop_tunnel(session_info, port)diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex 96b7172a2..8079e702e 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -505,6 +505,19 @@ Examples:p.add_argument('task', help='Task description')p.add_argument('--max-steps', type=int, default=100, help='Maximum steps')+ # -------------------------------------------------------------------------+ # Tunnel Commands+ # -------------------------------------------------------------------------++ tunnel_p = subparsers.add_parser('tunnel', help='Expose localhost via Cloudflare tunnel')+ tunnel_p.add_argument(+ 'port_or_subcommand',+ nargs='?',+ default=None,+ help='Port number to tunnel, or subcommand (list, stop)',+ )+ tunnel_p.add_argument('port_arg', nargs='?', type=int, help='Port number (for stop subcommand)')+# -------------------------------------------------------------------------# Session Management# -------------------------------------------------------------------------@@ -1165,6 +1178,28 @@ def main() -> int:print('No active sessions')return 0+ # Handle tunnel subcommand parsing+ if args.command == 'tunnel':+ pos = getattr(args, 'port_or_subcommand', None)+ if pos == 'list':+ params = {'subcommand': 'list'}+ elif pos == 'stop':+ port_arg = getattr(args, 'port_arg', None)+ if port_arg is None:+ print('Usage: browser-use tunnel stop <port>', file=sys.stderr)+ return 1+ params = {'subcommand': 'stop', 'port': port_arg}+ elif pos is not None:+ try:+ port = int(pos)+ except ValueError:+ print(f'Unknown tunnel subcommand: {pos}', file=sys.stderr)+ return 1+ params = {'subcommand': 'start', 'port': port}+ else:+ print('Usage: browser-use tunnel <port> | list | stop <port>', file=sys.stderr)+ return 0+# Set API key in environment if providedif args.api_key:os.environ['BROWSER_USE_API_KEY'] = args.api_key@@ -1184,13 +1219,14 @@ def main() -> int:# Ensure server is runningensure_server(args.session, args.browser, args.headed, args.profile, args.api_key)- # Build params from args- params = {}- skip_keys = {'command', 'session', 'browser', 'headed', 'profile', 'json', 'api_key', 'server_command'}+ # Build params from args (unless already built for tunnel)+ if args.command != 'tunnel':+ params = {}+ skip_keys = {'command', 'session', 'browser', 'headed', 'profile', 'json', 'api_key', 'server_command'}- for key, value in vars(args).items():- if key not in skip_keys and value is not None:- params[key] = value+ for key, value in vars(args).items():+ if key not in skip_keys and value is not None:+ params[key] = value# Send command to serverresponse = send_command(args.session, args.command, params)diff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.pyindex 4ae594f7d..f28024d52 100644--- a/browser_use/skill_cli/server.py+++ b/browser_use/skill_cli/server.py@@ -103,7 +103,7 @@ class SessionServer:try:# Import command handlers- from browser_use.skill_cli.commands import agent, browser, python_exec, session+ from browser_use.skill_cli.commands import agent, browser, python_exec, session, tunnel# Handle shutdownif action == 'shutdown':@@ -128,6 +128,8 @@ class SessionServer:# Dispatch to handlerif action in browser.COMMANDS:result = await browser.handle(action, session_info, params)+ elif action in tunnel.COMMANDS:+ result = await tunnel.handle(action, session_info, params)elif action == 'python':result = await python_exec.handle(session_info, params)elif action == 'run':diff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.pyindex c332c055d..57cceee70 100644--- a/browser_use/skill_cli/sessions.py+++ b/browser_use/skill_cli/sessions.py@@ -1,5 +1,6 @@"""Session registry - manages BrowserSession instances."""+import asyncioimport loggingfrom dataclasses import dataclass, fieldfrom typing import Any@@ -10,6 +11,15 @@ from browser_use.skill_cli.python_session import PythonSessionlogger = logging.getLogger(__name__)+@dataclass+class TunnelInfo:+ """Information about an active cloudflare tunnel."""++ port: int+ url: str+ process: asyncio.subprocess.Process++@dataclassclass SessionInfo:"""Information about a browser session."""@@ -20,6 +30,7 @@ class SessionInfo:profile: str | Nonebrowser_session: BrowserSessionpython_session: PythonSession = field(default_factory=PythonSession)+ tunnels: dict[int, TunnelInfo] = field(default_factory=dict)class SessionRegistry:@@ -81,6 +92,16 @@ class SessionRegistry:session = self._sessions.pop(name)logger.info(f'Closing session: {name}')++ # Stop all tunnels first+ if session.tunnels:+ from browser_use.skill_cli.commands.tunnel import stop_all_tunnels++ try:+ await stop_all_tunnels(session)+ except Exception as e:+ logger.warning(f'Error stopping tunnels for session {name}: {e}')+try:await session.browser_session.kill()except Exception as e:diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdnew file mode 100644index 000000000..aa9f126bb--- /dev/null+++ b/skills/remote-browser/SKILL.md@@ -0,0 +1,225 @@+---+name: remote-browser+description: Controls a cloud 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.+allowed-tools: Bash(browser-use:*)+---++# Remote Browser Automation for Sandboxed Agents++This skill is for agents running on **sandboxed remote machines** (cloud VMs, CI, coding agents) that need to control a browser. Install `browser-use` and drive a cloud browser — no local Chrome needed.++## Setup++```bash+pip install "browser-use[cli]"+# or: uv pip install "browser-use[cli]"++export BROWSER_USE_API_KEY=bu_xxx # Required for cloud browser+```++## Core Workflow++```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+```++The `open` command returns a `live_url` for cloud browsers — a real-time browser viewport you can view in any browser.++## Exposing Local Dev Servers++If you're running a dev server on the remote machine and need the cloud browser to reach it:++```bash+# Start your dev server+python -m http.server 3000 &++# Expose it via Cloudflare tunnel+browser-use tunnel 3000+# → url: https://abc.trycloudflare.com++# Now the cloud browser can reach your local server+browser-use --browser remote open https://abc.trycloudflare.com+```++Tunnel commands:+```bash+browser-use tunnel <port> # Start tunnel (returns URL)+browser-use tunnel <port> # Idempotent - returns existing URL+browser-use tunnel list # Show active tunnels+browser-use tunnel stop <port> # Stop tunnel+browser-use close # Closing session stops all tunnels+```++Requires `cloudflared` binary (`pip install cloudflared` or `brew install cloudflared`).++## Commands++### Navigation+```bash+browser-use open <url> # Navigate to URL+browser-use back # Go back in history+browser-use scroll down # Scroll down+browser-use scroll up # Scroll up+```++### Page State+```bash+browser-use state # Get URL, title, and clickable elements+browser-use screenshot # Take screenshot (base64)+browser-use screenshot path.png # Save screenshot to file+browser-use screenshot --full p.png # Full page screenshot+```++### Interactions (use indices from `state`)+```bash+browser-use click <index> # Click element+browser-use type "text" # Type into focused element+browser-use input <index> "text" # Click element, then type+browser-use keys "Enter" # Send keyboard keys+browser-use keys "Control+a" # Key combination+browser-use select <index> "option" # Select dropdown option+browser-use hover <index> # Hover over element+browser-use dblclick <index> # Double-click+browser-use rightclick <index> # Right-click+```++### JavaScript & Data+```bash+browser-use eval "document.title" # Execute JavaScript+browser-use get title # Get page title+browser-use get html # Get page HTML+browser-use get html --selector "h1" # Scoped HTML+browser-use get text <index> # Get element text+browser-use get value <index> # Get input value+browser-use get attributes <index> # Get element attributes+```++### Wait Conditions+```bash+browser-use wait selector "h1" # Wait for element+browser-use wait selector ".loading" --state hidden # Wait for element to disappear+browser-use wait text "Success" # Wait for text+browser-use wait selector "#btn" --timeout 5000 # Custom timeout (ms)+```++### Cookies+```bash+browser-use cookies get # Get all cookies+browser-use cookies set <name> <val> # Set a cookie+browser-use cookies clear # Clear all cookies+browser-use cookies export <file> # Export to JSON+browser-use cookies import <file> # Import from JSON+```++### Tab Management+```bash+browser-use switch <tab> # Switch tab by index+browser-use close-tab # Close current tab+browser-use close-tab <tab> # Close specific tab+```++### Agent Tasks+```bash+browser-use run "Fill the contact form with test data" # AI agent+browser-use run "Extract all product prices" --max-steps 50+```++### Session Management+```bash+browser-use sessions # List active sessions+browser-use close # Close current session+browser-use close --all # Close all sessions+```++### Global Options++| Option | Description |+|--------|-------------|+| `--session NAME` | Named session (default: "default") |+| `--browser remote` | Cloud browser (always use this on sandboxed machines) |+| `--profile ID` | Cloud profile ID for persistent cookies |+| `--json` | Output as JSON |+| `--api-key KEY` | Override API key |++## Common Patterns++### Test a Local Dev Server with Cloud Browser++```bash+# Start dev server+npm run dev & # localhost:3000++# Tunnel it+browser-use tunnel 3000+# → url: https://abc.trycloudflare.com++# Browse with cloud browser+browser-use --browser remote open https://abc.trycloudflare.com+browser-use state+browser-use screenshot+```++### Form Submission++```bash+browser-use --browser remote open https://example.com/contact+browser-use state+# Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"+browser-use input 0 "John Doe"+browser-use input 1 "[email protected]"+browser-use input 2 "Hello, this is a test message."+browser-use click 3+browser-use state # Verify success+```++### Screenshot Loop for Visual Verification++```bash+browser-use --browser remote open https://example.com+for i in 1 2 3 4 5; do+ browser-use scroll down+ browser-use screenshot "page_$i.png"+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++## Troubleshooting++**Cloud browser won't start?**+- Verify `BROWSER_USE_API_KEY` is set+- Check your API key at https://browser-use.com++**Tunnel not working?**+- Install cloudflared: `pip install cloudflared` or `brew install cloudflared`+- `browser-use tunnel list` to check active tunnels+- `browser-use tunnel stop <port>` and retry++**Element not found?**+- Run `browser-use state` to see current elements+- `browser-use scroll down` then `browser-use state` — element might be below fold+- Page may have changed — re-run `state` to get fresh indices++## Cleanup++**Always close the browser when done:**++```bash+browser-use close+```++This stops all tunnels and releases the cloud browser session.