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
docs: add multi-session and config sections to browser-use skill
ShawnPanac4d5a0eace20
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex 7616a1ea0..6a750f07f 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -219,6 +219,35 @@ browser-use --connect $INDEX click <element> # Click in agent's tab- **If you get "Tab is currently in use by another agent"**: do NOT close sessions or force it. Just use `open` to navigate your own tab to the URL you need.- **Never run `browser-use close --all`** when other agents are sharing the browser — it kills everything.+## Multiple Browser Sessions++Run different browsers simultaneously with `--session`:++```bash+browser-use --session cloud cloud connect # Cloud browser+browser-use --session local --headed open <url> # Local Chromium+browser-use --session work --profile "Default" open <url> # Real Chrome++browser-use sessions # List all active+browser-use --session cloud close # Close one+browser-use close --all # Close all+```++Each session gets its own daemon, socket, and state. See `references/multi-session.md` for details.++## Configuration++```bash+browser-use config list # Show all config values+browser-use config set cloud_connect_proxy jp # Set a value+browser-use config get cloud_connect_proxy # Get a value+browser-use config unset cloud_connect_timeout # Remove a value+browser-use doctor # Shows config + diagnostics+browser-use setup # Interactive post-install setup+```++Config stored in `~/.browser-use/config.json`.+## Global Options| Option | Description |diff --git a/skills/browser-use/references/multi-session.md b/skills/browser-use/references/multi-session.mdnew file mode 100644index 000000000..eb9a595ca--- /dev/null+++ b/skills/browser-use/references/multi-session.md@@ -0,0 +1,99 @@+# Multiple Browser Sessions++## Why use multiple sessions++When you need more than one browser at a time:+- Cloud browser for scraping + local Chrome for authenticated tasks+- Two different Chrome profiles simultaneously+- Isolated browser for testing that won't affect the user's browsing+- Running a headed browser for debugging while headless runs in background++## How sessions are isolated++Each `--session NAME` gets:+- Its own daemon process+- Its own Unix socket (`~/.browser-use/{name}.sock`)+- Its own PID file and state file+- Its own browser instance (completely independent)+- Its own tab ownership state (multi-agent locks don't cross sessions)++## The `--session` flag++Must be passed on every command targeting that session:++```bash+browser-use --session work open <url> # goes to 'work' daemon+browser-use --session work state # reads from 'work' daemon+browser-use state # goes to 'default' daemon (different browser)+```++If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser.++## Combining sessions with browser modes++```bash+# Session 1: cloud browser+browser-use --session cloud cloud connect++# Session 2: connect to user's Chrome with multi-agent+INDEX=$(browser-use register)+browser-use --session chrome --connect $INDEX open <url>++# Session 3: headed Chromium for debugging+browser-use --session debug --headed open <url>+```++Each session is fully independent. The cloud session talks to a remote browser, the chrome session talks to the user's Chrome, and the debug session manages its own Chromium — all running simultaneously.++## Agent indices and sessions++`browser-use register` writes to a shared `agents.json` (not per-session). An index like `1` can be used with any session that connects to the same Chrome. Typically you'd use `--connect` with one session and bare commands with others.++If two sessions both use `--connect` to the same Chrome, their tab ownership is independent — locks in one session don't protect tabs in the other. Use one session per Chrome instance for multi-agent work.++## Listing and managing sessions++```bash+browser-use sessions+```++Output:+```+SESSION PHASE PID CONFIG+cloud running 12345 cloud+chrome running 12346 cdp+debug ready 12347 headed+```++PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`.++```bash+browser-use --session cloud close # close one session+browser-use close --all # close every session+```++## Common patterns++**Cloud + local authenticated:**+```bash+browser-use --session scraper cloud connect+browser-use --session scraper open https://example.com+# ... scrape data ...++browser-use --session auth --profile "Default" open https://github.com+browser-use --session auth state+# ... interact with authenticated site ...+```++**Throwaway test browser:**+```bash+browser-use --session test --headed open https://localhost:3000+# ... test, debug, inspect ...+browser-use --session test close # done, clean up+```++**Environment variable:**+```bash+export BROWSER_USE_SESSION=work+browser-use open <url> # uses 'work' session without --session flag+```