Skip to content

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

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__.py
index 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.py
new file mode 100644
index 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.py
index 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 provided
if args.api_key:
os.environ['BROWSER_USE_API_KEY'] = args.api_key
@@ -1184,13 +1219,14 @@ def main() -> int:
# Ensure server is running
ensure_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 server
response = send_command(args.session, args.command, params)
diff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.py
index 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 shutdown
if action == 'shutdown':
@@ -128,6 +128,8 @@ class SessionServer:
# Dispatch to handler
if 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.py
index 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 asyncio
import logging
from dataclasses import dataclass, field
from typing import Any
@@ -10,6 +11,15 @@ from browser_use.skill_cli.python_session import PythonSession
logger = logging.getLogger(__name__)
+@dataclass
+class TunnelInfo:
+ """Information about an active cloudflare tunnel."""
+
+ port: int
+ url: str
+ process: asyncio.subprocess.Process
+
+
@dataclass
class SessionInfo:
"""Information about a browser session."""
@@ -20,6 +30,7 @@ class SessionInfo:
profile: str | None
browser_session: BrowserSession
python_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.md
new file mode 100644
index 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.