Browser Modes
June 2, 2026 · View on GitHub
Three browser modes by use case, all running on your machine:
| Mode | Scenario | Key trait |
|---|---|---|
| chrome | Reuse local Chrome login state | Two sub-modes: Profile import / CDP attach |
| stealth · privacy mode | Frictionless batch scraping without login | Fresh fingerprint per session + proxy rotation, zero residue |
| stealth · fixed identity | Logged-in accounts · multi-browser parallel | Stable fingerprint + stable IP, stable account identity, not flagged as bots |
chrome: Reuse Local Chrome Login State
Best for already-logged-in sites (Gmail, GitHub, Jira, etc.) when you don't want to log in again. Two sub-modes are available.
Sub-mode 1: Import Local Profile
Extract a Profile (cookies, localStorage, IndexedDB) from local Chrome into a standalone Chromium instance:
# List importable profiles
browser-act browser list-profiles
# Create a chrome browser with the chosen profile
browser-act browser create --type chrome --name "work" \
--desc "Work Chrome: logged into GitHub, Jira, Gmail" \
--source-profile <profile-id>
Properties:
- A standalone Chromium instance, isolated from your local Chrome
- Import is a one-time snapshot — later changes in local Chrome do not sync
- Quota: up to 20 browsers
- Suitable for long-running automation tasks
You can also import after creation
If the browser already exists, import separately:
browser-act browser import-profile <browser_id> <profile_id>
# If Chrome needs to be restarted to enable CDP
browser-act browser import-profile <browser_id> <profile_id> --allow-restart-chrome
What is imported
| Included | Excluded |
|---|---|
| Cookies | Browsing history |
| localStorage | Bookmarks |
| IndexedDB | Extensions |
| Session storage | Cache |
| Saved passwords |
Two import modes
| Mode | Path | Trait |
|---|---|---|
| Local mode | chrome → chrome | Direct file copy. Fastest, most complete |
| CDP mode | any → stealth, cross-type | Network extraction via DevTools Protocol |
Prerequisites
- Must call
browser list-profilesfirst to discover Profile IDs - The target browser must already exist (created via
browser create) - The source browser (Chrome) may need to be closed for local import
Risk Notes
Profile import has inherent risks the agent must communicate to users:
- The source browser may be closed during import.
- An IP change at the new location may trigger re-verification on some sites.
- Environment differences (fingerprint, location) may trigger re-login.
- Import is a snapshot — later changes at the source do not propagate.
Sub-mode 2: CDP Direct Attach
Directly drive your running local Chrome — extensions, certificates, and SSO are all in place:
browser-act browser create --type chrome-direct --name "live" --desc "Direct attach to local Chrome"
browser-act --session work browser open <browser-id> https://internal.corp.com
Properties:
- Zero configuration — no Profile import required
- Full inheritance of local Chrome's extensions, bookmarks, certificates, and SSO cookies
- Quota: 1 chrome-direct browser globally
- While running, your Chrome is being automated (you can't use it manually)
- Headed mode is not supported (since it's already your browser)
Best for: Enterprise SSO, sites that depend on specific extensions or certificates, quick operations that don't require isolation.
Comparing the Two Sub-modes
| Profile import | CDP attach | |
|---|---|---|
| Setup | Choose a profile to import | Zero config |
| Isolation | Standalone process | Your actual Chrome |
| Extensions / certs | Excluded from import | Fully inherited |
| Quota | 20 | 1 (global) |
| User's Chrome occupied? | No | Yes |
| Long-running tasks | ✓ | ✗ (occupies your Chrome) |
stealth · Privacy Mode: Login-Free Batch Scraping
Fresh fingerprint per session + auto-rotating proxy IPs, zero residue. Ideal for monitoring competitor sites at scale — prices, SKUs, new arrivals — with no traces left behind.
# Create a stealth browser with privacy mode + dynamic proxy
browser-act browser create --type stealth --name "monitor" \
--desc "Competitor price monitoring" \
--dynamic-proxy US \
--private true
Properties:
- Each
browser opensession gets a fresh fingerprint and an empty profile, nothing persisted - Dynamic proxy auto-rotates IPs by region
- Passes anti-detection in headless mode with full spoofing intact
- Best for one-off tasks, high-anonymity needs, and avoiding fingerprint accumulation
Trade-off: Login state is not retained; requires an API Key (managed service).
stealth · Fixed Identity: Logged-In Multi-Browser
Each browser keeps a stable fingerprint + stable IP, so the account looks like a real user. Scale to multiple independent browsers — accounts cannot be correlated across them.
Requires fixed IPs (dynamic proxies rotate). Recommended: use managed static proxies:
# List purchased static proxies
browser-act proxy list
# Each store gets its own stealth browser with a dedicated static proxy
browser-act browser create --type stealth --name "shop-1" \
--desc "Taobao store 1: women's clothing" \
--static-proxy <proxy_id_1>
browser-act browser create --type stealth --name "shop-2" \
--desc "Taobao store 2: electronics" \
--static-proxy <proxy_id_2>
Also supports --custom-proxy socks5://host:port if you bring your own fixed proxy.
Properties:
- Each browser has independent fingerprint, fixed proxy, and independent cookies
- Same browser keeps the same IP across uses — sites treat it as a stable real user
- Sites cannot correlate across browsers
- Login state persists; subsequent operations skip the login flow
- Best for multi-store management, multi-account operations, and multi-account competitive monitoring
Trade-off: Requires an API Key (managed service). Managed static proxies require purchase; custom proxies are bring-your-own.
Picking a Mode by Task
| Task | Pick |
|---|---|
| Automate a site you're already logged into in Chrome | chrome with Profile import |
| Need local extensions, certificates, or SSO | chrome-direct (CDP) |
| Scrape public content protected by anti-scraping | stealth privacy mode + proxy |
| Run multiple independent accounts long-term | stealth fixed identity (one browser per account) |
| Just need to read a page once | stealth-extract (no browser to create) |
Real-World Switching Paths
Scenario 1: From chrome to stealth
You automate an e-commerce site with chrome. After a few days, captchas start appearing. Switch to stealth privacy mode — a "clean identity" continues, avoiding correlation.
Scenario 2: From stealth to chrome-direct
You log into an enterprise system with stealth, but it depends on a specific browser extension. Switch to chrome-direct to attach to your local Chrome (with the extension already installed).
Scenario 3: From chrome-direct to chrome
You ran a task with chrome-direct successfully. But chrome-direct has only one quota and you don't want to occupy your local Chrome each time. Import the login state into a chrome browser and use chrome from then on.
Quotas
| Type | Max | Notes |
|---|---|---|
chrome (incl. chrome-direct) | 20 + 1 | chrome: 20 standalone processes; chrome-direct: 1 global |
stealth | Per account | Allocated based on the account |
Unified Data Model
Regardless of mode, every browser shares the same structure:
| Field | Description |
|---|---|
id | Unique identifier, auto-generated |
name | Human-readable name |
type | chrome / chrome-direct / stealth |
desc | Natural-language purpose description (see Agent Design) |
dynamic_proxy | Managed proxy region code (stealth only) |
static_proxy | Managed static proxy ID (stealth only) |
custom_proxy | Custom proxy URL (stealth only) |
private | Privacy mode toggle, default false (stealth only) |
confirm_before_use | Whether to ask the user before each use |
Next Steps
- Anti-Blocking — Anti-scraping deep dive for stealth browsers
- Concurrency & Isolation — Multi-browser parallel patterns
- Agent Design — desc semantic memory and browser selection logic