Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs: guide agents from free credits to a bounded Cloud run

Gregor Žunič2db9f6ef0295
diff --git a/README.md b/README.md
index 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.
+
# Quickstart
If 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.md
index 01dfea136..6773134df 100644
--- a/skills/cloud/SKILL.md
+++ b/skills/cloud/SKILL.md
@@ -21,6 +21,16 @@ allowed-tools: Read
Reference 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.md
index 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 BrowserUse
with 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 the
status 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: