browser-use--browser-harness
Gregor Žunič
82 行
4.4 KiB
Markdown
82 行
4.4 KiB
Markdown
# Profile sync
|
|
|
|
Advanced only. Use this when the user explicitly asks to upload local Chrome cookies into Browser Use cloud profiles. For normal cloud browser work, use `browser_new("cloud")`, keep the returned `id`, and call `browser(id)` before page helpers.
|
|
|
|
This file manages cloud cookie profiles. It does not replace the explicit browser id flow.
|
|
|
|
## One-time install
|
|
|
|
```bash
|
|
curl -fsSL https://browser-use.com/profile.sh | sh
|
|
```
|
|
|
|
Downloads `profile-use` (macOS / Linux, x64 / arm64). The Python helpers shell out to it; you don't run `profile-use` directly.
|
|
|
|
## Python API (pre-imported in `browser-harness`)
|
|
|
|
```python
|
|
list_cloud_profiles()
|
|
# [{id, name, userId, cookieDomains, lastUsedAt}, ...] — every profile under this API key
|
|
|
|
browser_profiles(verbose=True)
|
|
# {"profiles": [{"id", "profile_name", "display_name", "profile_path", ...}, ...]}
|
|
|
|
sync_local_profile(profile_name, browser=None,
|
|
cloud_profile_id=None, # update an existing cloud profile instead of creating new
|
|
include_domains=None, # only these domains (and subdomains); leading dot optional
|
|
exclude_domains=None) # drop these domains; applied before include
|
|
# Shells out to `profile-use sync`. Returns the cloud profile UUID
|
|
# (the existing one if cloud_profile_id was passed, else the newly-created one).
|
|
```
|
|
|
|
`sync_local_profile` prints `♻️ Using existing cloud profile` when `cloud_profile_id` is accepted, or `📝 Creating remote profile...` → `✓ Profile created: <uuid>` when it creates a new one. Check that line if you want to confirm which path ran.
|
|
|
|
## Chat-driven flow (don't guess — ask the user)
|
|
|
|
Cookies are real auth. Don't sync or pick a profile unilaterally.
|
|
|
|
```python
|
|
# 1. Show what's already in the cloud.
|
|
for p in list_cloud_profiles():
|
|
print(f"{p['name']:25} {len(p['cookieDomains']):3} domains {p['id']}")
|
|
```
|
|
→ Agent: *"You have these cloud profiles (<N> domains each). Want to reuse one, sync a local profile, or start clean?"*
|
|
|
|
```python
|
|
# 2. Sync local first. Show the options:
|
|
for lp in browser_profiles(verbose=True)["profiles"]:
|
|
print(lp["id"], lp["display_name"])
|
|
```
|
|
→ Agent: *"Which local profile?"* → user picks → before syncing, inspect domain-level cookie counts with `profile-use inspect --profile <name>` (or `--verbose` for individual cookies) and report the summary; never dump 500 cookies into chat.
|
|
|
|
```python
|
|
# 3. Sync. Returns the cloud profile UUID.
|
|
uuid = sync_local_profile("browser-use.com")
|
|
print({"cloud_profile_id": uuid})
|
|
|
|
# 3b. Refresh that same cloud profile later (idempotent — no duplicate profiles).
|
|
sync_local_profile("browser-use.com", cloud_profile_id=uuid)
|
|
|
|
# 3c. Scoped: push *only* Stripe cookies into a dedicated cloud profile.
|
|
sync_local_profile("browser-use.com",
|
|
cloud_profile_id=uuid,
|
|
include_domains=["stripe.com"])
|
|
```
|
|
|
|
## What actually gets synced
|
|
|
|
**Cookies only.** No localStorage, no IndexedDB, no extensions. Enough for session-cookie sites (Google, GitHub, Stripe, most SaaS); not for sites that store auth in localStorage.
|
|
|
|
## Cloud profile CRUD
|
|
|
|
- UI: https://cloud.browser-use.com/settings?tab=profiles
|
|
- API: `GET /profiles`, `GET/PATCH/DELETE /profiles/{id}` (paths are relative to `BU_API = "https://api.browser-use.com/api/v3"` in `admin.py`). Fields: `id`, `name`, `userId`, `lastUsedAt`, `cookieDomains[]`. `list_cloud_profiles()` wraps this.
|
|
- Need the UUID for an existing profile? `matches = [p["id"] for p in list_cloud_profiles() if p["name"] == "<name>"]` — then verify `len(matches) == 1` before using it. Profile names are not unique; syncs create duplicates unless you pass `cloud_profile_id=`.
|
|
- Lower-level raw calls: `from browser_harness.admin import _browser_use; _browser_use("/profiles/<id>", "DELETE")`. Pass the path *without* the `/api/v3` prefix — it's already on `BU_API`.
|
|
|
|
## Traps
|
|
|
|
- **Default proxy (`proxyCountryCode="us"`) blocks some destinations** with `ERR_TUNNEL_CONNECTION_FAILED` (e.g. `cloud.browser-use.com` itself). `proxyCountryCode=None` disables the BU proxy; a different country code picks a different exit.
|
|
- **Prefer a dedicated work profile over your personal one.** Especially while testing.
|
|
- **Older than `profile-use` v1.0.5?** Pre-1.0.5 the sync needed the Chrome profile to be closed (exclusive SQLite lock on the `Cookies` DB). v1.0.5+ copies the profile dir to a temp and syncs from the copy — Chrome can stay open.
|