browser-act--skills/docs/browser-modes.md

Browser Modes

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-profiles first 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:

1. The source browser may be closed during import.
2. An IP change at the new location may trigger re-verification on some sites.
3. Environment differences (fingerprint, location) may trigger re-login.
4. 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 open session 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