1# Multiple Browser Sessions
2 
3## Why use multiple sessions
4 
5When you need more than one browser at a time:
6- Cloud browser for scraping + local Chrome for authenticated tasks
7- Two different Chrome profiles simultaneously
8- Isolated browser for testing that won't affect the user's browsing
9- Running a headed browser for debugging while headless runs in background
10 
11## How sessions are isolated
12 
13Each `--session NAME` gets:
14- Its own daemon process
15- Its own Unix socket (`~/.browser-use/{name}.sock`)
16- Its own PID file and state file
17- Its own browser instance (completely independent)
18- Its own tab ownership state (multi-agent locks don't cross sessions)
19 
20## The `--session` flag
21 
22Must be passed on every command targeting that session:
23 
24```bash
25browser-use --session work open <url>      # goes to 'work' daemon
26browser-use --session work state           # reads from 'work' daemon
27browser-use state                          # goes to 'default' daemon (different browser)
28```
29 
30If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser.
31 
32## Combining sessions with browser modes
33 
34```bash
35# Session 1: cloud browser
36browser-use --session cloud cloud connect
37 
38# Session 2: connect to user's Chrome
39browser-use --session chrome connect
40 
41# Session 3: headed Chromium for debugging
42browser-use --session debug --headed open <url>
43```
44 
45Each 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.
46 
47## Listing and managing sessions
48 
49```bash
50browser-use sessions
51```
52 
53Output:
54```
55SESSION          PHASE          PID      CONFIG
56cloud            running        12345    cloud
57chrome           running        12346    cdp
58debug            ready          12347    headed
59```
60 
61PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`.
62 
63```bash
64browser-use --session cloud close           # close one session
65browser-use close --all                     # close every session
66```
67 
68## Common patterns
69 
70**Cloud + local authenticated:**
71```bash
72browser-use --session scraper cloud connect
73browser-use --session scraper open https://example.com
74# ... scrape data ...
75 
76browser-use --session auth --profile "Default" open https://github.com
77browser-use --session auth state
78# ... interact with authenticated site ...
79```
80 
81**Throwaway test browser:**
82```bash
83browser-use --session test --headed open https://localhost:3000
84# ... test, debug, inspect ...
85browser-use --session test close    # done, clean up
86```
87 
88**Environment variable:**
89```bash
90export BROWSER_USE_SESSION=work
91browser-use open <url>              # uses 'work' session without --session flag
92```
93