Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
docs: guide agents from free credits to a bounded Cloud run
Gregor Žunič2db9f6ef0295
diff --git a/README.md b/README.mdindex 8535f304b..fc106f967 100644--- a/README.md+++ b/README.md@@ -62,6 +62,14 @@ https://github.com/user-attachments/assets/485fd3ec-61b9-4afc-9e86-ee9b85acb592<br/>+# Start with Browser Use Cloud++Eligible new Google, GitHub, or Microsoft signups receive a one-time $15 Cloud credit. No credit card is required. Email/password signups are not eligible; the credit does not renew. Start with the default V4 model (`gpt-5.6-luna`); paid-only models require a top-up. See [pricing](https://browser-use.com/pricing.md) for current eligibility and rates.++- **Give a task to a hosted agent:** use the [V4 Cloud SDK quickstart](https://docs.browser-use.com/cloud/agent/quickstart). Install `browser-use-sdk`, then call `client.runs.create`.+- **Bring your own agent or automation:** use the [managed browser quickstart](https://docs.browser-use.com/cloud/browser/quickstart) for SDK or CDP control.+- **Run and customize the framework locally:** use the Python library below. The `browser-use` package has a different API from the Cloud SDK.+# QuickstartIf you want to use Browser Use in your agent (Claude Code, Codex, Cursor, Hermes, OpenClaw, etc.), paste this prompt, and it sets everything up itself:diff --git a/skills/cloud/SKILL.md b/skills/cloud/SKILL.mdindex 01dfea136..6773134df 100644--- a/skills/cloud/SKILL.md+++ b/skills/cloud/SKILL.md@@ -21,6 +21,16 @@ allowed-tools: ReadReference docs for the Cloud REST API, SDKs, and integration patterns.Read the relevant file based on what the user needs.+## Choose a starter++- Hosted task in, result out: use the V4 SDK `runs` resource in `references/api-v4.md`.+- Your existing agent needs a browser: use the V4 SDK `browsers` resource or REST/CDP, then explicitly stop the browser.+- Local framework development: use the open-source `browser-use` skill, not Cloud SDK calls.++Eligible new Google, GitHub, or Microsoft signups receive a one-time $15 Cloud credit. No credit card is required. Email/password signups are not eligible; the credit does not renew. Start with the default V4 model (`gpt-5.6-luna`); paid-only models require a top-up. See [pricing](https://browser-use.com/pricing.md) for current eligibility and rates.++Reuse `BROWSER_USE_API_KEY` if available. Otherwise direct the user to Cloud signup and API-key creation; keep the key in a server-side environment variable, never a prompt or client bundle. Do not promise anonymous signup.+## API & Platform| Topic | Read |@@ -56,5 +66,5 @@ Read the relevant file based on what the user needs.- TypeScript v2: `import { BrowserUse } from "browser-use-sdk"`- TypeScript v3: `import { BrowserUse } from "browser-use-sdk/v3"`- TypeScript v4: `import { BrowserUse } from "browser-use-sdk/v4"`-- Browser management is available at the v4 REST `/browsers` resource, but its SDK wrapper still uses the explicit v3 namespace. Always stop a browser explicitly; closing CDP does not stop billing.+- SDK 3.11.3 or newer exposes `browsers.create` and `browsers.stop` in the v4 namespace, alongside the v4 REST `/browsers` resource. Always stop a browser explicitly; closing CDP does not stop billing.- CDP WebSocket: `wss://connect.browser-use.com?apiKey=KEY&proxyCountryCode=us`diff --git a/skills/cloud/references/api-v4.md b/skills/cloud/references/api-v4.mdindex 64180974f..0d3d49ac0 100644--- a/skills/cloud/references/api-v4.md+++ b/skills/cloud/references/api-v4.md@@ -9,6 +9,12 @@ is the persistent filesystem that can be reused across sessions.- Python: `from browser_use_sdk.v4 import BrowserUse`- TypeScript: `import { BrowserUse } from "browser-use-sdk/v4"`+## Before the first run++Eligible new Google, GitHub, or Microsoft signups receive a one-time $15 Cloud credit. No credit card is required. Email/password signups are not eligible; the credit does not renew. Start with the default V4 model (`gpt-5.6-luna`); paid-only models require a top-up. See [pricing](https://browser-use.com/pricing.md) for current eligibility and rates.++Install or upgrade `browser-use-sdk` to 3.11.3 or newer. Read `BROWSER_USE_API_KEY` from the environment; do not embed it in source or a prompt.+## First Run### Python@@ -17,8 +23,12 @@ is the persistent filesystem that can be reused across sessions.from browser_use_sdk.v4 import BrowserUsewith BrowserUse() as client:- created = client.runs.create("Find the top Hacker News story")+ created = client.runs.create(+ "Open https://example.com and return its title", max_cost_usd=0.10+ )run = client.runs.wait_for_completion(created.id)+ if run.status != "completed":+ raise RuntimeError(f"Run {run.id}: {run.status}")print(run.result)```@@ -29,9 +39,13 @@ import { BrowserUse } from "browser-use-sdk/v4";const client = new BrowserUse();const created = await client.runs.create({- task: "Find the top Hacker News story",+ task: "Open https://example.com and return its title",+ maxCostUsd: 0.10,});const run = await client.runs.waitForCompletion(created.id);+if (run.status !== "completed") {+ throw new Error(`Run ${run.id}: ${run.status}`);+}console.log(run.result);```@@ -53,6 +67,8 @@ curl https://api.browser-use.com/api/v4/runs/RUN_ID \-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"```+Only `completed` means success. V4 returns a result string; parse and validate it in your application. A polling timeout does not cancel the remote run: use `client.runs.cancel` if abandoning it. Do not blindly retry an ambiguous create request, which could start duplicate paid work.+Do not repeatedly poll the full run resource. The SDK wait helpers use thestatus route and fetch the full run once at the end.@@ -114,10 +130,11 @@ The v4 REST API can create a browser for direct CDP control:3. `PATCH /browsers/{session_id}` with `{"action":"stop"}` stops the browser;replace `session_id` with the returned `id`.-Closing a CDP client does not stop the cloud browser or its billing. The-browser-management SDK wrapper currently uses the explicit v3 namespace; use-`browser_use_sdk.v3` or `browser-use-sdk/v3` for that resource, or call the v4-REST endpoint directly.+Closing a CDP client does not stop the cloud browser or its billing. SDK+3.11.3 or newer exposes `client.browsers.create()` and+`client.browsers.stop(browser.id)` through `browser_use_sdk.v4` and+`browser-use-sdk/v4`. Put the explicit stop in a `finally` block so failures+also clean up the browser. Existing V3 integrations can keep their imports.## Resource Map@@ -126,7 +143,7 @@ REST endpoint directly.| Runs | create, list, get, status, events, cancel, attachments || Sessions | list, get, queue messages, inspect/remove queued messages, purge || Workspaces | create, get, update, archive, size, upload/list/delete files |-| Browsers (REST) | create, inspect, stop |+| Browsers | SDK: create, stop; REST: create, inspect, stop |For the complete current contract, use: