Skip to content

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

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.md
index 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.md
new file mode 100644
index 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
+```