Browser Automation via cloudrouter browser

Automate browser interactions in cloud sandboxes. cloudrouter browser wraps agent-browser and runs commands inside the sandbox via SSH.

Prerequisite: You need a running cloudrouter sandbox. Get the sandbox ID from cloudrouter ls or create one with cloudrouter start . .

Core Workflow

Always follow this pattern: Open -> Snapshot -> Interact -> Re-snapshot

cloudrouter browser open <id> "https://example.com" cloudrouter browser snapshot -i <id> # -i = interactive elements only cloudrouter browser click <id> @e5 # Click element ref cloudrouter browser fill <id> @e3 "text" # Fill input cloudrouter browser snapshot -i <id> # Re-snapshot after change

Essential Commands

Navigation

cloudrouter browser open <id> <url> # Navigate to URL cloudrouter browser back <id> # Go back cloudrouter browser forward <id> # Go forward cloudrouter browser reload <id> # Refresh page cloudrouter browser url <id> # Get current URL cloudrouter browser title <id> # Get page title

Inspection

cloudrouter browser snapshot -i <id> # Interactive elements only (RECOMMENDED) cloudrouter browser snapshot <id> # Full accessibility tree cloudrouter browser snapshot -c <id> # Compact output cloudrouter browser screenshot <id> # Screenshot (base64 to stdout) cloudrouter browser screenshot <id> out.png # Save screenshot to file cloudrouter browser screenshot --full <id> # Full page screenshot cloudrouter browser eval <id> "document.title" # Run JavaScript

Interaction

cloudrouter browser click <id> @e1 # Click element cloudrouter browser dblclick <id> @e1 # Double-click cloudrouter browser fill <id> @e2 "text" # Clear input and type text cloudrouter browser type <id> @e2 "text" # Type without clearing (appends) cloudrouter browser press <id> Enter # Press key (Enter, Tab, Escape, etc.) cloudrouter browser hover <id> @e5 # Hover over element cloudrouter browser focus <id> @e3 # Focus element cloudrouter browser scroll <id> down # Scroll down (default pixels) cloudrouter browser scroll <id> down 500 # Scroll down 500px cloudrouter browser scroll <id> up # Scroll up cloudrouter browser scrollintoview <id> "#element" # Scroll into view (CSS selector only, NOT @e refs) cloudrouter browser select <id> @e7 "value" # Select dropdown option cloudrouter browser check <id> @e8 # Check checkbox cloudrouter browser uncheck <id> @e9 # Uncheck checkbox cloudrouter browser upload <id> @e10 /path # Upload file cloudrouter browser drag <id> @e1 @e2 # Drag and drop cloudrouter browser wait <id> @e3 # Wait for element to appear cloudrouter browser wait <id> 2000 # Wait milliseconds

Get Information

cloudrouter browser get-text <id> @e1 # Get element text cloudrouter browser get-value <id> @e2 # Get input value cloudrouter browser get-attr <id> @e3 href # Get attribute cloudrouter browser get-html <id> @e4 # Get innerHTML cloudrouter browser get-count <id> ".item" # Count matching elements cloudrouter browser is-visible <id> @e1 # Check visibility cloudrouter browser is-enabled <id> @e1 # Check if enabled cloudrouter browser is-checked <id> @e1 # Check if checked

Semantic Locators (alternative to refs)

When refs are unreliable on dynamic pages:

cloudrouter browser find <id> text "Sign In" click # By visible text cloudrouter browser find <id> label "Email" fill "user@test.com" # By label cloudrouter browser find <id> placeholder "Search" type "query" # By placeholder cloudrouter browser find <id> testid "submit-btn" click # By data-testid

Note: find <id> role button click finds the FIRST button on the page — it cannot filter by name. Use find <id> text "Button Name" click to target a specific button. There is no --name flag.

JavaScript & Debugging

cloudrouter browser eval <id> "document.title" # Evaluate JS cloudrouter browser console <id> # View console output cloudrouter browser errors <id> # View JS errors

Tabs & Frames

cloudrouter browser tab-list <id> # List tabs cloudrouter browser tab-new <id> "https://..." # New tab cloudrouter browser tab-switch <id> 2 # Switch tab cloudrouter browser tab-close <id> # Close tab cloudrouter browser frame <id> "#iframe" # Switch to iframe cloudrouter browser frame <id> main # Back to main

Cookies & Storage

cloudrouter browser cookies <id> # List cookies cloudrouter browser cookies-set <id> name value # Set cookie cloudrouter browser cookies-clear <id> # Clear cookies cloudrouter browser storage-local <id> # Get localStorage cloudrouter browser storage-local-set <id> key value # Set localStorage cloudrouter browser storage-local-clear <id> # Clear localStorage

State Management

cloudrouter browser state-save <id> /tmp/auth.json # Save cookies + storage cloudrouter browser state-load <id> /tmp/auth.json # Restore state

Browser Settings

cloudrouter browser set-viewport <id> 1920 1080 # Set viewport cloudrouter browser set-device <id> "iPhone 14" # Emulate device cloudrouter browser set-geo <id> 37.77 -122.42 # Set geolocation cloudrouter browser set-offline <id> on # Toggle offline cloudrouter browser set-media <id> dark # Color scheme

Network Interception

cloudrouter browser network-route <id> "/api/*" # Intercept requests cloudrouter browser network-route <id> "/ads/*" --abort # Block requests cloudrouter browser network-unroute <id> # Remove routes cloudrouter browser network-requests <id> # List requests

Dialogs

cloudrouter browser dialog-accept <id> # Accept alert/confirm cloudrouter browser dialog-accept <id> "answer" # Accept prompt with text cloudrouter browser dialog-dismiss <id> # Dismiss dialog

Element Selectors

• Element refs from snapshot: @e1 , @e2 , @e3 ... (preferred)

• CSS selectors: #id , .class , button[type="submit"]

Snapshot output shows [ref=e1] — use as @e1 in commands.

Common Patterns

Login Flow

cloudrouter browser open <id> "https://app.example.com/login" cloudrouter browser snapshot -i <id>

→ @e1 [input] Email, @e2 [input] Password, @e3 [button] Sign In

cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password123" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser snapshot -i <id> # Verify login success cloudrouter browser screenshot <id> /tmp/result.png

Form Submission

cloudrouter browser open <id> "https://example.com/contact" cloudrouter browser snapshot -i <id> cloudrouter browser fill <id> @e1 "John Doe" cloudrouter browser fill <id> @e2 "john@email.com" cloudrouter browser fill <id> @e3 "Hello world" cloudrouter browser click <id> @e4 # Submit cloudrouter browser wait <id> 2000 cloudrouter browser snapshot -i <id> # Verify submission

Data Extraction

cloudrouter browser open <id> "https://example.com/products" cloudrouter browser snapshot <id> # Full tree for structure cloudrouter browser get-text <id> @e5 # Extract specific text cloudrouter browser eval <id> "JSON.stringify([...document.querySelectorAll('.product')].map(p => p.textContent))"

Multi-page Navigation

cloudrouter browser open <id> "https://example.com" cloudrouter browser snapshot -i <id> cloudrouter browser click <id> @e3 # Click a link cloudrouter browser wait <id> 2000 # Wait for page load cloudrouter browser snapshot -i <id> # ALWAYS re-snapshot after navigation

Auth State Persistence

Login once and save state

cloudrouter browser open <id> "https://app.example.com/login" cloudrouter browser snapshot -i <id> cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser state-save <id> /tmp/auth.json

Restore in future sessions

cloudrouter browser state-load <id> /tmp/auth.json cloudrouter browser open <id> "https://app.example.com/dashboard"

Critical Rules

Flags go BEFORE the sandbox ID. cloudrouter browser snapshot -i <id> works. cloudrouter browser snapshot <id> -i silently returns empty/wrong results.

ALWAYS re-snapshot after navigation or clicks. Page content changes, refs become stale.

Use -i flag for snapshots — interactive elements only, much more efficient.

Don't mix snapshot modes. Full snapshot and snapshot -i assign DIFFERENT ref numbers. Stick to one mode (use -i ).

Use fill not type for form fields. fill clears first; type appends.

Refs are temporary. They reset after each snapshot. Always use fresh refs.

Verify before interacting. Check snapshot output to confirm you have the right element.

Handle loading states. If elements are missing, wait and re-snapshot.

Troubleshooting

Issue Solution

Element not found / wrong element Re-snapshot with -i , refs are stale

snapshot <id> -i returns empty Put flags BEFORE id: snapshot -i <id>

Click doesn't work Try hover first, then click

Page not loading Check URL with cloudrouter browser url <id>

Browser not ready Wait a few seconds after sandbox creation, retry

Refs differ between snapshots Don't mix full and -i snapshots

Form field has old text Use fill (clears first) instead of type

find ... role button click clicks wrong button Use find ... text "Button Name" click instead

find ... --name "X" fails There is no --name flag — use text locator

npm install EACCES error Run cloudrouter ssh <id> "sudo chown -R 1000:1000 /home/user/.npm" first

scrollintoview @e1 fails with "Unsupported token" scrollintoview and highlight only accept CSS selectors ("#id" , ".class" ), NOT @e refs

pkill -f kills SSH session (exit 143/255) pkill -f pattern may match the SSH session. Just run another command to recover

pdf saves to remote, not local File saves inside sandbox (e.g. /tmp/page.pdf ). Use cloudrouter download to retrieve

storage-local <id> key shows "Done" not value Use eval <id> "localStorage.getItem('key')" to get a specific localStorage value

Stale ref error: "Action timed out" Always re-snapshot after clicks/form submits that change the DOM