agent-browser-stealth 0.17.0-fork.2 → 0.24.0-fork.2

package/skills/agent-browser/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: agent-browser
 description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
-allowed-tools: Bash(npx agent-browser-stealth:*), Bash(npx agent-browser:*), Bash(agent-browser:*), Bash(abs:*)
+allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
 ---
 
 # Browser Automation with agent-browser
 
-Install package: `pnpm add -g agent-browser-stealth` (CLI commands: `agent-browser`, `agent-browser-stealth`, and short alias `abs`). If global install is unavailable in your environment, use `pnpm dlx agent-browser-stealth <command>` for one-off runs.
-
-Use `agent-browser start` when you want to pre-warm the managed automation browser on `localhost:9333` before the actual navigation or task commands run.
+The CLI uses Chrome/Chromium via CDP directly. Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome. Existing Chrome, Brave, Playwright, and Puppeteer installations are detected automatically. Run `agent-browser upgrade` to update to the latest version.
 
 ## Core Workflow
 
@@ -48,31 +46,85 @@ agent-browser open https://example.com && agent-browser wait --load networkidle
 
 **When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs).
 
+## Handling Authentication
+
+When automating a site that requires login, choose the approach that fits:
+
+**Option 1: Import auth from the user's browser (fastest for one-off tasks)**
+
+```bash
+# Connect to the user's running Chrome (they're already logged in)
+agent-browser --auto-connect state save ./auth.json
+# Use that auth state
+agent-browser --state ./auth.json open https://app.example.com/dashboard
+```
+
+State files contain session tokens in plaintext -- add to `.gitignore` and delete when no longer needed. Set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest.
+
+**Option 2: Persistent profile (simplest for recurring tasks)**
+
+```bash
+# First run: login manually or via automation
+agent-browser --profile ~/.myapp open https://app.example.com/login
+# ... fill credentials, submit ...
+
+# All future runs: already authenticated
+agent-browser --profile ~/.myapp open https://app.example.com/dashboard
+```
+
+**Option 3: Session name (auto-save/restore cookies + localStorage)**
+
+```bash
+agent-browser --session-name myapp open https://app.example.com/login
+# ... login flow ...
+agent-browser close  # State auto-saved
+
+# Next time: state auto-restored
+agent-browser --session-name myapp open https://app.example.com/dashboard
+```
+
+**Option 4: Auth vault (credentials stored encrypted, login by name)**
+
+```bash
+echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
+agent-browser auth login myapp
+```
+
+`auth login` navigates with `load` and then waits for login form selectors to appear before filling/clicking, which is more reliable on delayed SPA login screens.
+
+**Option 5: State file (manual save/load)**
+
+```bash
+# After logging in:
+agent-browser state save ./auth.json
+# In a future session:
+agent-browser state load ./auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+See [references/authentication.md](references/authentication.md) for OAuth, 2FA, cookie-based auth, and token refresh patterns.
+
 ## Essential Commands
 
 ```bash
 # Navigation
-agent-browser start                   # Start/reuse managed browser on localhost:9333
 agent-browser open <url>              # Navigate (aliases: goto, navigate)
-agent-browser --risk-mode block open <url>  # Block if verification/captcha interstitial is detected
-agent-browser doctor                  # Diagnose CDP + sourceURL + tab-group plugin health
 agent-browser close                   # Close browser
-agent-browser --version               # Show CLI version (fork builds include upstream/fork)
+agent-browser close --all             # Close all active sessions
 
 # Snapshot
 agent-browser snapshot -i             # Interactive elements with refs (recommended)
-agent-browser snapshot -i -C          # Include cursor-interactive elements (divs with onclick, cursor:pointer)
 agent-browser snapshot -s "#selector" # Scope to CSS selector
 
 # Interaction (use @refs from snapshot)
 agent-browser click @e1               # Click element
 agent-browser click @e1 --new-tab     # Click and open in new tab
 agent-browser fill @e2 "text"         # Clear and type text
-agent-browser type @e2 "text" --delay 120  # Type without clearing (human-like pacing)
+agent-browser type @e2 "text"         # Type without clearing
 agent-browser select @e1 "option"     # Select dropdown option
 agent-browser check @e1               # Check checkbox
 agent-browser press Enter             # Press key
-agent-browser keyboard type "text" --delay 90  # Type at current focus (no selector)
+agent-browser keyboard type "text"    # Type at current focus (no selector)
 agent-browser keyboard inserttext "text"  # Insert without key events
 agent-browser scroll down 500         # Scroll page
 agent-browser scroll down 500 --selector "div.content"  # Scroll within a specific container
@@ -81,26 +133,66 @@ agent-browser scroll down 500 --selector "div.content"  # Scroll within a specif
 agent-browser get text @e1            # Get element text
 agent-browser get url                 # Get current URL
 agent-browser get title               # Get page title
+agent-browser get cdp-url             # Get CDP WebSocket URL
 
 # Wait
 agent-browser wait @e1                # Wait for element
 agent-browser wait --load networkidle # Wait for network idle
 agent-browser wait --url "**/page"    # Wait for URL pattern
 agent-browser wait 2000               # Wait milliseconds
-agent-browser wait 2000-5000          # Random wait between 2-5 seconds
+agent-browser wait --text "Welcome"    # Wait for text to appear (substring match)
+agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
+agent-browser wait "#spinner" --state hidden  # Wait for element to disappear
 
 # Downloads
 agent-browser download @e1 ./file.pdf          # Click element to trigger download
 agent-browser wait --download ./output.zip     # Wait for any download to complete
 agent-browser --download-path ./downloads open <url>  # Set default download directory
-agent-browser --tab-group "My Agent Group" open <url>  # Override default tab-group base title
+
+# Network
+agent-browser network requests                 # Inspect tracked requests
+agent-browser network requests --type xhr,fetch  # Filter by resource type
+agent-browser network requests --method POST   # Filter by HTTP method
+agent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)
+agent-browser network request <requestId>      # View full request/response detail
+agent-browser network route "**/api/*" --abort  # Block matching requests
+agent-browser network har start                # Start HAR recording
+agent-browser network har stop ./capture.har   # Stop and save HAR file
+
+# Viewport & Device Emulation
+agent-browser set viewport 1920 1080          # Set viewport size (default: 1280x720)
+agent-browser set viewport 1920 1080 2        # 2x retina (same CSS size, higher res screenshots)
+agent-browser set device "iPhone 14"          # Emulate device (viewport + user agent)
 
 # Capture
 agent-browser screenshot              # Screenshot to temp dir
 agent-browser screenshot --full       # Full page screenshot
 agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
+agent-browser screenshot --screenshot-dir ./shots  # Save to custom directory
+agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
 agent-browser pdf output.pdf          # Save as PDF
 
+# Live preview / streaming
+agent-browser stream enable           # Start runtime WebSocket streaming on an auto-selected port
+agent-browser stream enable --port 9223  # Bind a specific localhost port
+agent-browser stream status           # Inspect enabled state, port, connection, and screencasting
+agent-browser stream disable          # Stop runtime streaming and remove the .stream metadata file
+
+# Clipboard
+agent-browser clipboard read                      # Read text from clipboard
+agent-browser clipboard write "Hello, World!"     # Write text to clipboard
+agent-browser clipboard copy                      # Copy current selection
+agent-browser clipboard paste                     # Paste from clipboard
+
+# Dialogs (alert, confirm, prompt, beforeunload)
+# By default, alert and beforeunload dialogs are auto-accepted so they never block the agent.
+# confirm and prompt dialogs still require explicit handling.
+# Use --no-auto-dialog (or AGENT_BROWSER_NO_AUTO_DIALOG=1) to disable automatic handling.
+agent-browser dialog accept              # Accept dialog
+agent-browser dialog accept "my input"   # Accept prompt dialog with text
+agent-browser dialog dismiss             # Dismiss/cancel dialog
+agent-browser dialog status              # Check if a dialog is currently open
+
 # Diff (compare page states)
 agent-browser diff snapshot                          # Compare current vs last snapshot
 agent-browser diff snapshot --baseline before.txt    # Compare current vs saved file
@@ -110,6 +202,28 @@ agent-browser diff url <url1> <url2> --wait-until networkidle  # Custom wait str
 agent-browser diff url <url1> <url2> --selector "#main"  # Scope to element
 ```
 
+## Streaming
+
+Every session automatically starts a WebSocket stream server on an OS-assigned port. Use `agent-browser stream status` to see the bound port and connection state. Use `stream disable` to tear it down, and `stream enable --port <port>` to re-enable on a specific port.
+
+## Batch Execution
+
+Execute multiple commands in a single invocation by piping a JSON array of string arrays to `batch`. This avoids per-command process startup overhead when running multi-step workflows.
+
+```bash
+echo '[
+  ["open", "https://example.com"],
+  ["snapshot", "-i"],
+  ["click", "@e1"],
+  ["screenshot", "result.png"]
+]' | agent-browser batch --json
+
+# Stop on first error
+agent-browser batch --bail < commands.json
+```
+
+Use `batch` when you have a known sequence of commands that don't depend on intermediate output. Use separate commands or `&&` chaining when you need to parse output between steps (e.g., snapshot to discover refs, then interact).
+
 ## Common Patterns
 
 ### Form Submission
@@ -141,6 +255,8 @@ agent-browser auth show github
 agent-browser auth delete github
 ```
 
+`auth login` waits for username/password/submit selectors before interacting, with a timeout tied to the default action timeout.
+
 ### Authentication with State Persistence
 
 ```bash
@@ -158,25 +274,10 @@ agent-browser state load auth.json
 agent-browser open https://app.example.com/dashboard
 ```
 
-### Cookie Injection for Auth Callbacks
-
-```bash
-# Before navigation: set by URL
-agent-browser cookies set session_id "abc123" --url https://app.example.com/api/auth/sso/callback
-
-# Explicit domain/path pair (must be provided together)
-agent-browser cookies set auth_token "xyz789" --domain .example.com --path /api
-
-# Or navigate first and rely on current URL
-agent-browser open https://app.example.com/api/auth/sso/callback
-agent-browser cookies set callback_token "token123"
-```
-
 ### Session Persistence
 
 ```bash
 # Auto-save/restore cookies and localStorage across browser restarts
-# If --session-name is omitted, it defaults to "default"
 agent-browser --session-name myapp open https://app.example.com/login
 # ... login flow ...
 agent-browser close  # State auto-saved to ~/.agent-browser/sessions/
@@ -195,6 +296,30 @@ agent-browser state clear myapp
 agent-browser state clean --older-than 7
 ```
 
+### Working with Iframes
+
+Iframe content is automatically inlined in snapshots. Refs inside iframes carry frame context, so you can interact with them directly.
+
+```bash
+agent-browser open https://example.com/checkout
+agent-browser snapshot -i
+# @e1 [heading] "Checkout"
+# @e2 [Iframe] "payment-frame"
+#   @e3 [input] "Card number"
+#   @e4 [input] "Expiry"
+#   @e5 [button] "Pay"
+
+# Interact directly — no frame switch needed
+agent-browser fill @e3 "4111111111111111"
+agent-browser fill @e4 "12/28"
+agent-browser click @e5
+
+# To scope a snapshot to one iframe:
+agent-browser frame @e2
+agent-browser snapshot -i         # Only iframe content
+agent-browser frame main          # Return to main frame
+```
+
 ### Data Extraction
 
 ```bash
@@ -208,59 +333,30 @@ agent-browser snapshot -i --json
 agent-browser get text @e1 --json
 ```
 
-### Parallel Workflows
+### Parallel Sessions
 
 ```bash
-agent-browser --parallel site1 open https://site-a.com
-agent-browser --parallel site2 open https://site-b.com
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
 
-agent-browser --parallel site1 snapshot -i
-agent-browser --parallel site2 snapshot -i
-```
+agent-browser --session site1 snapshot -i
+agent-browser --session site2 snapshot -i
 
-Use `--parallel <name>` for stateless throughput tasks (navigation, extraction, checks). For login/auth continuity, use `--session-name` instead.
-Default-session commands intentionally reap all non-default daemon sessions (`parallel-*` and legacy named channels) to prevent stale daemon reuse.
+agent-browser session list
+```
 
 ### Connect to Existing Chrome
 
-By default in this fork, commands without `--cdp` use a dedicated automation browser with this order:
-
-1. Try CDP at `localhost:9333`
-2. If unavailable, auto-start Chrome with the persistent profile `~/.agent-browser/chrome-bot-profile`
-3. If managed `:9333` startup fails, exit with guidance
-
 ```bash
-# Explicitly attach to an existing manual Chrome session
+# Auto-discover running Chrome with remote debugging enabled
 agent-browser --auto-connect open https://example.com
 agent-browser --auto-connect snapshot
 
 # Or with explicit CDP port
 agent-browser --cdp 9222 snapshot
-
-# Debug auto-attach behavior
-agent-browser --debug snapshot
-
-# Diagnose CDP + sourceURL + plugin handshake status
-agent-browser doctor
-
-# Avoid `open` timeout on challenge-heavy pages
-agent-browser --wait-until domcontentloaded open https://example.com
-
-# Deterministic Turnstile smoke check (official test key)
-pnpm run check:turnstile-testkey
 ```
 
-### Daemon Lifecycle
-
-Daemons auto-shutdown after 10 minutes of inactivity.
-
-Use `--resident` for long-running workflows that should not auto-close:
-
-```bash
-agent-browser --resident open https://example.com
-# keep running until explicit close
-agent-browser close
-```
+Auto-connect discovers Chrome via `DevToolsActivePort`, common debugging ports (9222, 9229), and falls back to a direct WebSocket connection if HTTP-based CDP discovery fails.
 
 ### Color Scheme (Dark Mode)
 
@@ -275,51 +371,41 @@ AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
 agent-browser set media dark
 ```
 
-### Tab Grouping
+### Viewport & Responsive Testing
 
 ```bash
-# CDP mode groups tabs when tab-group extension is installed
-agent-browser open https://example.com
+# Set a custom viewport size (default is 1280x720)
+agent-browser set viewport 1920 1080
+agent-browser screenshot desktop.png
 
-# Override the default group title
-agent-browser --tab-group "My Agent Group" open https://example.com
+# Test mobile-width layout
+agent-browser set viewport 375 812
+agent-browser screenshot mobile.png
 
-# Or via environment variable
-AGENT_BROWSER_TAB_GROUP="My Agent Group" agent-browser open https://example.com
-
-# Override expected extension ID if needed
-AGENT_BROWSER_TAB_GROUP_PLUGIN_ID="<extension-id>" agent-browser open https://example.com
-```
-
-Notes:
-
-- Works in CDP mode via extension handshake.
-- Extension package name in Chrome: `agent-browser-stealth`.
-- Extension installed and reachable: tabs are grouped by session.
-- Extension missing/unavailable: silent no-op (no warning/error unless debug mode).
-- Default titles:
-  - `default` session: `Agent Browser Stealth`
-  - non-default session: `Agent Browser Stealth • <session>`
-- Additional extension-side capabilities:
-  - Session window isolation + deterministic group colors.
-  - Side panel browser controls: `open` / `back` / `forward` / `reload` + selector-based `click` / `fill` / `press`.
-  - Side panel developer signals: page console events, fetch/xhr network events, command history, and on-demand DOM snapshots.
-  - Side panel automation: action recording, workflow run, slash shortcut binding, and scheduled execution (daily/weekly/monthly/yearly).
-  - Side panel operations: Focus / Keep Only This / Clean Empty Groups + isolation/auto-clean toggles.
-  - Session allowlist policy editing and fallback blocking (`about:blank`).
-  - Download auto-routing to `agent-browser-stealth/<session>/...`.
+# Retina/HiDPI: same CSS layout at 2x pixel density
+# Screenshots stay at logical viewport size, but content renders at higher DPI
+agent-browser set viewport 1920 1080 2
+agent-browser screenshot retina.png
+
+# Device emulation (sets viewport + user agent in one step)
+agent-browser set device "iPhone 14"
+agent-browser screenshot device.png
+```
+
+The `scale` parameter (3rd argument) sets `window.devicePixelRatio` without changing CSS layout. Use it when testing retina rendering or capturing higher-resolution screenshots.
 
 ### Visual Browser (Debugging)
 
 ```bash
 agent-browser --headed open https://example.com
 agent-browser highlight @e1          # Highlight element
+agent-browser inspect                # Open Chrome DevTools for the active page
 agent-browser record start demo.webm # Record session
 agent-browser profiler start         # Start Chrome DevTools profiling
 agent-browser profiler stop trace.json # Stop and save profile (path optional)
 ```
 
-Use `AGENT_BROWSER_HEADED=1` or `AGENT_BROWSER_HEADED=true` to enable headed mode via environment variable. In this fork, local launches and extension launches stay headed by default unless headless is explicitly requested.
+Use `AGENT_BROWSER_HEADED=1` to enable headed mode via environment variable. Browser extensions work in both headed and headless mode.
 
 ### Local Files (PDFs, HTML)
 
@@ -330,42 +416,6 @@ agent-browser --allow-file-access open file:///path/to/page.html
 agent-browser screenshot output.png
 ```
 
-### Project Policy
-
-- `--profile` / `AGENT_BROWSER_PROFILE` are forbidden
-- `--channel` / `AGENT_BROWSER_CHANNEL` are forbidden
-- Default mode uses the managed CDP browser on `localhost:9333`; use `--auto-connect` only for explicit existing-browser attachment
-
-### Stealth Mode (Always On)
-
-Stealth is always active -- no flags needed. All sessions automatically apply anti-detection patches (navigator.webdriver removal, UA override, plugin injection, WebGL masking, humanized interactions, etc.).
-
-Chromium launches in managed mode use Chrome channel by default for a genuine browser binary fingerprint.
-
-For best results against strong bot detection, use `--headed` and keep one stable `--session-name`.
-
-### Auto Region Detection
-
-The browser automatically detects the target site's region from the URL TLD and sets matching locale, timezone, and Accept-Language headers. For example, navigating to `shopee.tw` sets locale `zh-TW` and timezone `Asia/Taipei`. This reduces server-side risk scoring from region-signal mismatches.
-
-Override: `AGENT_BROWSER_LOCALE`, `AGENT_BROWSER_TIMEZONE` env vars.
-
-### Captcha Detection & Auto-Retry
-
-When a navigation lands on a captcha/verification page, behavior is controlled by `--risk-mode` (or `AGENT_BROWSER_RISK_MODE`):
-
-- `warn` (default): wait for auto-clear first, then retry up to 2 times with randomized backoff (3-7s), then return warning plus structured `riskSignals`
-- `block`: fail fast once a risk interstitial is detected
-- `off`: disable this detection/retry path
-
-Examples:
-
-```bash
-agent-browser --risk-mode warn open https://example.com
-agent-browser --risk-mode block open https://example.com
-AGENT_BROWSER_RISK_MODE=off agent-browser open https://example.com
-```
-
 ### iOS Simulator (Mobile Safari)
 
 ```bash
@@ -470,7 +520,7 @@ agent-browser diff url https://staging.example.com https://prod.example.com --sc
 
 ## Timeouts and Slow Pages
 
-The default Playwright timeout is 25 seconds for local browsers. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
+The default timeout is 25 seconds. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
 
 ```bash
 # Wait for network activity to settle (best for slow pages)
@@ -488,35 +538,58 @@ agent-browser wait --fn "document.readyState === 'complete'"
 
 # Wait a fixed duration (milliseconds) as a last resort
 agent-browser wait 5000
-
-# Random wait between 2-5 seconds (useful for anti-detection)
-agent-browser wait 2000-5000
 ```
 
 When dealing with consistently slow websites, use `wait --load networkidle` after `open` to ensure the page is fully loaded before taking a snapshot. If a specific element is slow to render, wait for it directly with `wait <selector>` or `wait @ref`.
 
-### Humanized Interactions
+## JavaScript Dialogs (alert / confirm / prompt)
+
+When a page opens a JavaScript dialog (`alert()`, `confirm()`, or `prompt()`), it blocks all other browser commands (snapshot, screenshot, click, etc.) until the dialog is dismissed. If commands start timing out unexpectedly, check for a pending dialog:
+
+```bash
+# Check if a dialog is blocking
+agent-browser dialog status
+
+# Accept the dialog (dismiss the alert / click OK)
+agent-browser dialog accept
 
-agent-browser automatically humanizes interactions to avoid behavioral detection:
+# Accept a prompt dialog with input text
+agent-browser dialog accept "my input"
 
-- **Randomized typing**: `type --delay` varies each keystroke delay by +-40%
-- **Random wait ranges**: `wait 2000-5000` pauses for a random duration in that range
-- **Bezier curve mouse**: Before every `click`, the mouse moves along a natural-looking curve
+# Dismiss the dialog (click Cancel)
+agent-browser dialog dismiss
+```
 
-These behaviors are always active. For sensitive sites, combine with `--headed` and a stable `--session-name` for best results.
+When a dialog is pending, all command responses include a `warning` field indicating the dialog type and message. In `--json` mode this appears as a `"warning"` key in the response object.
 
 ## Session Management and Cleanup
 
-`--session` is ignored in this fork. Runtime defaults to `default`; use `--parallel <name>` for isolated concurrent channels, and `--session-name` for persistence isolation.
-When a default-session command runs, non-default daemon sessions are reaped automatically.
+When running multiple agents or automations concurrently, always use named sessions to avoid conflicts:
+
+```bash
+# Each agent gets its own isolated session
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+
+# Check active sessions
+agent-browser session list
+```
 
 Always close your browser session when done to avoid leaked processes:
 
 ```bash
-agent-browser close
+agent-browser close                    # Close default session
+agent-browser --session agent1 close   # Close specific session
+agent-browser close --all              # Close all active sessions
 ```
 
-If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up before starting new work.
+If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up, or `agent-browser close --all` to shut down every session at once.
+
+To auto-shutdown the daemon after a period of inactivity (useful for ephemeral/CI environments):
+
+```bash
+AGENT_BROWSER_IDLE_TIMEOUT_MS=60000 agent-browser open example.com
+```
 
 ## Ref Lifecycle (Important)
 
@@ -601,7 +674,8 @@ Create `agent-browser.json` in the project root for persistent settings:
 ```json
 {
   "headed": true,
-  "proxy": "http://localhost:8080"
+  "proxy": "http://localhost:8080",
+  "profile": "./browser-data"
 }
 ```
 
@@ -619,20 +693,24 @@ Priority (lowest to highest): `~/.agent-browser/config.json` < `./agent-browser.
 | [references/profiling.md](references/profiling.md)                   | Chrome DevTools profiling for performance analysis        |
 | [references/proxy-support.md](references/proxy-support.md)           | Proxy configuration, geo-testing, rotating proxies        |
 
-## Experimental: Native Mode
+## Cloud Providers
 
-agent-browser has an experimental native Rust daemon that communicates with Chrome directly via CDP, bypassing Node.js and Playwright entirely. It is opt-in and not recommended for production use yet.
+Use `-p <provider>` (or `AGENT_BROWSER_PROVIDER`) to run against a cloud browser instead of launching a local Chrome instance. Supported providers: `agentcore`, `browserbase`, `browserless`, `browseruse`, `kernel`.
+
+### AgentCore (AWS Bedrock)
 
 ```bash
-# Enable via flag
-agent-browser --native open example.com
+# Credentials auto-resolved from env vars or AWS CLI (SSO, IAM roles, etc.)
+agent-browser -p agentcore open https://example.com
 
-# Enable via environment variable (avoids passing --native every time)
-export AGENT_BROWSER_NATIVE=1
-agent-browser open example.com
+# With persistent browser profile
+AGENTCORE_PROFILE_ID=my-profile agent-browser -p agentcore open https://example.com
+
+# With explicit region
+AGENTCORE_REGION=eu-west-1 agent-browser -p agentcore open https://example.com
 ```
 
-The native daemon supports Chromium and Safari (via WebDriver). Firefox and WebKit are not yet supported. All core commands (navigate, snapshot, click, fill, screenshot, cookies, storage, tabs, eval, etc.) work identically in native mode. Use `agent-browser close` before switching between native and default mode within the same session.
+Set `AWS_PROFILE` to select a named AWS profile.
 
 ## Browser Engine Selection
 
@@ -646,16 +724,35 @@ agent-browser --engine lightpanda open example.com
 export AGENT_BROWSER_ENGINE=lightpanda
 agent-browser open example.com
 
-# With a custom binary path
+# With custom binary path
 agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com
 ```
 
 Supported engines:
-
 - `chrome` (default) -- Chrome/Chromium via CDP
-- `lightpanda` -- Lightpanda headless browser via CDP
+- `lightpanda` -- Lightpanda headless browser via CDP (10x faster, 10x less memory than Chrome)
+
+Lightpanda does not support `--extension`, `--profile`, `--state`, or `--allow-file-access`. Install Lightpanda from https://lightpanda.io/docs/open-source/installation.
+
+## Observability Dashboard
+
+The dashboard is a standalone background server that shows live browser viewports, command activity, and console output for all sessions.
+
+```bash
+# Install the dashboard once
+agent-browser dashboard install
+
+# Start the dashboard server (background, port 4848)
+agent-browser dashboard start
+
+# All sessions are automatically visible in the dashboard
+agent-browser open example.com
+
+# Stop the dashboard
+agent-browser dashboard stop
+```
 
-Lightpanda is headless-only and does not support `--extension`, `--state`, `--profile`, or `--allow-file-access`. Install it from https://lightpanda.io/docs/open-source/installation.
+The dashboard runs independently of browser sessions on port 4848 (configurable with `--port`). All sessions automatically stream to the dashboard. Sessions can also be created from the dashboard UI with local engines or cloud providers.
 
 ## Ready-to-Use Templates