hyperbrowser 1.12.0__tar.gz → 1.13.0__tar.gz

hyperbrowser-1.13.0/PKG-INFO

@@ -0,0 +1,1074 @@
+Metadata-Version: 2.4
+Name: hyperbrowser
+Version: 1.13.0
+Summary: Python SDK for hyperbrowser
+License: MIT
+License-File: LICENSE
+Author: Nikhil Shahi
+Author-email: nshahi1998@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: cryptography (>=41.0.0)
+Requires-Dist: httpx (>=0.23.0,<1)
+Requires-Dist: jsonref (>=1.1.0)
+Requires-Dist: pydantic (>=2.0,<3)
+Requires-Dist: typing-extensions (>=4.0,<5)
+Requires-Dist: websockets (>=13,<18)
+Project-URL: Homepage, https://github.com/hyperbrowserai/python-sdk
+Project-URL: Repository, https://github.com/hyperbrowserai/python-sdk
+Description-Content-Type: text/markdown
+
+# Hyperbrowser Python SDK
+
+Checkout the full documentation [here](https://hyperbrowser.ai/docs)
+
+## Installation
+
+Currently Hyperbrowser supports creating a browser session in two ways:
+
+- Async Client
+- Sync Client
+
+It can be installed from `pypi` by running :
+
+```shell
+pip install hyperbrowser
+```
+
+The browser-control examples below also use Playwright:
+
+```shell
+pip install playwright
+```
+
+## Configuration
+
+Both the sync and async client follow similar configuration params
+
+### API Key
+The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
+
+If no API key is provided, the client falls back to a saved OAuth session created by `hx auth login`. By default it reads `~/.hx_config/auth/default.json`, or `~/.hx_config/auth/<profile>.json` when `HYPERBROWSER_PROFILE` or `ClientConfig(profile=...)` is set.
+
+Profile names must match `^[A-Za-z0-9._-]+$`.
+
+`base_url` and `HYPERBROWSER_BASE_URL` accept either `https://host` or `https://host/api`. The client normalizes both to the same control-plane base URL.
+
+## WebMCP page tools
+
+Create a session with `{"enable_web_mcp": True}` (default: false), then navigate
+to a page that exposes WebMCP tools using Playwright. With that session open:
+
+```python
+discovery = client.sessions.webmcp.list_tools(session.id)
+# Select a tool using its name, source page/frame, and input schema.
+tool = next(tool for tool in discovery.tools if tool.name == "search")
+result = client.sessions.webmcp.invoke(session.id, {
+    "tool_ref": tool.tool_ref,
+    "input": {"query": "flights to Tokyo"},  # Match the selected tool's schema.
+})
+print(result.status, result.output)
+```
+
+For long-running tools or forms awaiting human submission, use
+`client.sessions.webmcp.start(session_id, params)`, then
+`client.sessions.webmcp.get_result(session_id, invocation_id, {"wait_seconds": 30})`
+until the status is terminal. `client.sessions.webmcp.cancel(session_id, invocation_id)`
+requests best-effort cancellation. Blocking invocation defaults to 60 seconds
+(maximum 120); `start` defaults to 300 seconds (maximum 3,600) via `timeout_seconds`.
+All five methods also work with `AsyncHyperbrowser` by adding `await`.
+
+Discover tools again after navigation. Invocations never automatically retry;
+losing a response can leave an unknown outcome. Handles are ephemeral and
+terminal results expire after 10 minutes or earlier eviction. Check result
+status and truncation metadata before using output. Tool input and output keys
+are not renamed. Request TypedDicts are available in `hyperbrowser.types`, and
+Pydantic request/response models in `hyperbrowser.models`.
+
+See the [WebMCP guide](https://hyperbrowser.ai/docs/sessions/webmcp) for complete
+examples, cancellation behavior, human submission, and limits.
+
+## Web Bot Auth
+
+A session can sign its requests with Web Bot Auth so websites can verify that they
+come from Hyperbrowser. Web Bot Auth is enabled for teams on request.
+
+```python
+session = client.sessions.create({"web_bot_auth": True})
+print(session.launch_state.web_bot_auth.signature_agent)  # https://www.hyperbrowser.ai
+
+# Sign only requests to these hosts and their subdomains:
+client.sessions.create({"web_bot_auth": {"only_domains": ["example.com"]}})
+```
+
+Agent tasks accept `web_bot_auth` in `session_options`; scrape, crawl, and extract
+jobs do not. It cannot be combined with `use_ultra_stealth` or
+`start_from_snapshot`. See the
+[Web Bot Auth guide](https://hyperbrowser.ai/docs/sessions/web-bot-auth).
+
+## Proxy routes
+
+`proxy_routes` sends some hosts' traffic straight out instead of through the
+session's proxy, or the other way round. The first route that matches a host
+decides; hosts that no route matches use the proxy. Proxy routes require
+`use_proxy` and are enabled for teams on request.
+
+```python
+session = client.sessions.create({
+    "use_proxy": True,
+    "proxy_routes": [
+        {"match": "api.example.com", "proxy": "default"},  # stays on the proxy
+        {"match": ["*.example.com", "cdn.example.net"], "proxy": "direct"},
+    ],
+})
+```
+
+A pattern is a hostname, `*.example.com` (its subdomains, not `example.com`
+itself), or `*` (every host). Proxy routes only apply to `client.sessions.create`
+and cannot be combined with `allow_internet_access=False`, `allow_out`, or
+`deny_out`. See the
+[proxy routes guide](https://hyperbrowser.ai/docs/sessions/proxy-routes).
+
+## Fill credentials into browser sessions
+
+Any secret with allowed origins can be typed into pages of a browser session.
+A website login is usually two such secrets grouped in a vault, plus a TOTP
+secret when the site asks for a one-time code. Values are encrypted on your
+machine; after upload, neither the API, your code, nor an LLM sees them again.
+
+```python
+from playwright.sync_api import sync_playwright
+
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+origins = ["https://github.com"]
+client.secrets.create(
+    {"name": "github-username", "value": "ada@example.com", "allowed_origins": origins}
+)
+client.secrets.create(
+    {"name": "github-password", "value": "correct horse", "allowed_origins": origins}
+)
+# A TOTP seed: base32 as the site shows it, or an otpauth://totp/ URI.
+client.secrets.create(
+    {
+        "name": "github-otp",
+        "type": "totp",
+        "value": "JBSW Y3DP EHPK 3PXP JBSW Y3DP EHPK 3PXP",
+        "allowed_origins": origins,
+    }
+)
+client.vaults.create(
+    {
+        "name": "github-login",
+        "entries": {
+            "USERNAME": {"name": "github-username"},
+            "PASSWORD": {"name": "github-password"},
+            "OTP": {"name": "github-otp"},
+        },
+    }
+)
+
+# Secrets and vaults can only be attached when the session is created.
+session = client.sessions.create({"credentials": [{"vault": "github-login"}]})
+
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.ws_endpoint)
+    page = browser.contexts[0].pages[0]
+    page.goto("https://github.com/login")
+
+    # With a vault, each field names the entry to type.
+    result = client.sessions.credentials.fill(
+        session.id,
+        {
+            "vault": "github-login",
+            "fields": [
+                {"field": "USERNAME", "selector": "#login_field"},
+                {"field": "PASSWORD", "selector": "#password"},
+            ],
+        },
+    )
+    if all(field.outcome == "filled" for field in result.fields):
+        page.click("input[type=submit]")  # Fill only types; submitting is up to you.
+
+    page.wait_for_selector("#app_totp")
+    # A TOTP entry types the code that is current at fill time.
+    client.sessions.credentials.fill(
+        session.id,
+        {"vault": "github-login", "fields": [{"field": "OTP", "selector": "#app_totp"}]},
+    )
+
+client.sessions.stop(session.id)
+```
+
+A single secret works without a vault: attach it by name (`"credentials":
+["github-password"]` or `[{"secret": "github-password"}]`) and fill it with
+`{"credential": "github-password", "fields": [{"selector": "#password"}]}`.
+
+`fill()` returns the filled page's `page_id` and `origin`, the `version` for a
+single-secret fill, and per input its `selector`, `outcome`, `secret_id`,
+`version`, `field` (vault fills), `reference` (1Password fills) and
+`expires_at` (TOTP codes). Values are never returned.
+
+| Outcome | Meaning |
+| --- | --- |
+| `filled` | The input now holds the value. |
+| `not_found` | No input matched the selector. |
+| `ambiguous` | Several visible inputs matched the selector. |
+| `not_editable` | The input is disabled, read-only, hidden, or not a text input. |
+| `not_accepted` | The page didn't keep the value, for example because of `maxlength`. |
+
+Things to know:
+
+- A secret can be filled only on its allowed origins (`scheme://host[:port]`;
+  `https://*.example.com` matches any subdomain but not `example.com` itself).
+  A secret takes 1-20 of at most 512 characters, https only (http for
+  `localhost`, `127.0.0.1` and `[::1]`), with no path and `*.` only on a
+  registrable domain such as `example.com`, never `*.com` or an IP address.
+  The API validates and normalizes them.
+  Change them with `client.secrets.set_allowed_origins("github-password",
+  [...])`; `None` clears them, after which it can't be filled.
+  `client.secrets.update()` takes `{"metadata": {"browser": None}}` too: each
+  metadata member sent replaces the stored one and `None` removes it.
+- Secret types are `secret` (the default), `totp` and `op_token`, fixed at
+  creation; `client.secrets.list({"type": "totp"})` filters by type. TOTP
+  values are checked locally before upload: a base32 seed (spaces, hyphens, line breaks,
+  lowercase and trailing `=` are fine) or an `otpauth://totp/` URI with
+  `algorithm` SHA1/SHA256/SHA512, `digits` 6 or 8 and `period` 1-300. Seeds
+  shorter than 10 bytes (16 characters) are accepted but weak. The platform
+  can't read values, so a bad seed would otherwise only fail when used. A TOTP
+  secret delivered to a sandbox holds the code current at process start.
+- A fill takes one of `credential`, `vault` and `one_password`, and 1-16
+  fields with unique selectors; `field` is required with a vault and left out
+  without one, and `ref` is required with `one_password` and left out without
+  it.
+  Without `page_id`, fill considers the tabs whose URL starts with `page_url`
+  (all tabs when it's not given). If one is left, that's the target. If several
+  are left, it prefers the tabs on an origin every secret allows (skipped with
+  `frame_url`, since a login frame's tab is usually on another origin), then
+  the visible one among them; if more than one still qualifies, it fails with
+  `CREDENTIAL_PAGE_AMBIGUOUS`. The chosen tab's origin is then checked: on any
+  other origin nothing is typed and the fill fails with
+  `CREDENTIAL_ORIGIN_NOT_ALLOWED`. Under Playwright every tab reports as visible, so pass
+  `page_url` (a URL prefix) or the tab's CDP target ID as `page_id`:
+  `page.context.new_cdp_session(page).send("Target.getTargetInfo")["targetInfo"]["targetId"]`.
+  For a login form in an iframe, pass `frame_url` (a URL prefix).
+- Fill is safe to retry and never retried automatically. It waits at least
+  30 seconds for the API (the client timeout when longer).
+- Attaching secrets needs an API key with `secrets.use`; filling also needs
+  `browser.sessions.update`. The team needs the secrets feature. Sessions with
+  credentials run as Firecracker browsers with Chrome's password manager off.
+  A vault attaches the secrets its entries hold when the session is created.
+- Fills are recorded in the session's event log as `credential_filled` and
+  `credential_fill_refused`. Their metadata names the `credential` or `vault`;
+  for 1Password fills, `onePasswordToken` (the op_token's name) and its
+  `secretId`.
+- Errors are raised as `HyperbrowserError` with the API's `code`, `retryable`,
+  and `status_code`. `details` holds the API's response body, so the
+  candidate tabs of an ambiguous fill are in `error.details["details"]["pages"]`
+  (each with `pageId`, `url` and `title`). Error codes from the API:
+  - `CREDENTIAL_PAGE_AMBIGUOUS` (409): several tabs could be the target; pass
+    one's `pageId` as `page_id`, or a `page_url`. `CREDENTIAL_FRAME_AMBIGUOUS`
+    (409) is the same for frames.
+  - `CREDENTIAL_ORIGIN_NOT_ALLOWED` (403): the page's origin (in `details`)
+    isn't allowed; nothing was typed.
+  - `CREDENTIAL_NOT_ATTACHED` (403): the secret (or a 1Password fill's
+    op_token) wasn't attached when the session was created, or a vault entry
+    now points at another secret.
+  - `CREDENTIAL_NOT_READY` (409): the secret has no allowed origins or no
+    value.
+  - `SECRET_TYPE_MISMATCH` (409): an `op_token` can't be attached or filled
+    as a secret (by name, `{"secret": ...}` or a vault entry); attach it with
+    `{"one_password": ...}` instead. Also another type named as one.
+  - `SECRET_VALUE_INVALID` (422): the stored value is unusable, such as a bad
+    TOTP seed; add a new version.
+  - `CREDENTIAL_PAGE_NOT_FOUND`, `CREDENTIAL_FRAME_NOT_FOUND`,
+    `SECRET_NOT_FOUND`, `SECRET_VERSION_NOT_FOUND`, `VAULT_NOT_FOUND`,
+    `VAULT_ENTRY_NOT_FOUND` (404), `SESSION_NOT_ACTIVE` (409).
+  - `CREDENTIAL_FILL_TIMEOUT` (503/504, retryable) and
+    `CREDENTIAL_FILL_FAILED` (500/502/503, retryable as flagged).
+  - `CREDENTIALS_UNSUPPORTED_RUNTIME` (400), `CREDENTIAL_FILL_UNSUPPORTED`
+    (501) and `CREDENTIAL_VALUE_UNSUPPORTED` (501): the session's browser
+    can't fill this, such as 1Password fields on an older host.
+  - `SECRET_ONEPASSWORD_REFERENCE_FAILED` (422): a 1Password item or field
+    couldn't be read, so nothing was filled. `details` has the failing
+    `selectors` and `reasons` by selector. `SECRET_ONEPASSWORD_AUTH_FAILED`
+    (422): 1Password rejected the token, or the token is malformed or doesn't
+    sign in to `1password.com`, `.ca` or `.eu` (or a subdomain), so it wasn't
+    sent to 1Password. `SECRET_ONEPASSWORD_RATE_LIMITED` (429) and
+    `SECRET_ONEPASSWORD_FAILED` (502/503) are retryable. Each has the
+    token's `tokenSecretId` and `tokenVersion` in `details`.
+  - Local fill shape errors raise `invalid_request`; invalid secret values
+    raise `invalid_secret_value` before upload. Fill, origin, vault-entry and
+    1Password policy errors come from the API. Inspect the status, code (when
+    supplied) and details; schema errors may have no machine code.
+
+### Fill from 1Password
+
+A fill can also type fields of a 1Password vault, read with a 1Password
+service account token stored as an `op_token` secret (see
+[Manage secrets](#manage-secrets-and-pass-them-to-sandbox-processes)). Attach
+the token when creating the session, then name the vault, the origins the
+values may be typed on, and each input's field:
+
+```python
+session = client.sessions.create({"credentials": [{"one_password": "op-token"}]})
+# ... open https://www.scrapingcourse.com/login in the session ...
+result = client.sessions.credentials.fill(
+    session.id,
+    {
+        "one_password": {
+            "token": "op-token",  # the op_token secret; its latest version signs in
+            "vault": "Dev Vault",  # the 1Password vault's name or ID
+            # Nothing stored says where a 1Password value belongs, so the
+            # request names the origins it may be typed on.
+            "allowed_origins": ["https://www.scrapingcourse.com"],
+        },
+        "fields": [
+            {"selector": "#email", "ref": {"item": "scrapingcourse login", "field": "username"}},
+            {"selector": "#password", "ref": {"item": "scrapingcourse login", "field": "password"}},
+            {
+                "selector": "#otp",
+                "ref": {"item": "scrapingcourse login", "section": "Security", "field": "otp?attribute=totp"},
+            },
+        ],
+        "page_url": "https://www.scrapingcourse.com/login",
+    },
+)
+for field in result.fields:
+    print(field.selector, field.outcome, field.reference)  # op://Dev Vault/...
+```
+
+- `token` names the op_token secret, which must be attached to the session
+  (`{"one_password": name}` counts toward the 20 credentials). An op_token is
+  never typed itself, and attaching or filling it as a plain secret fails with
+  `SECRET_TYPE_MISMATCH`.
+- `allowed_origins` takes 1-20 origins with the same rules as a secret's.
+  A page on another origin fails with
+  `CREDENTIAL_ORIGIN_NOT_ALLOWED`, as for stored secrets.
+- `ref` is `{"item", "section"?, "field"}` by name or ID, with the same rules
+  as a sandbox's `one_password` fields: a field may end with a query such as
+  `?attribute=otp`, and `op://<vault>/<item>/[<section>/]<field>` is at most
+  512 bytes. Every field takes `ref` and none takes `field`.
+- The result has no top-level `version`; each input's `secret_id` and
+  `version` are the op_token's, and `reference` is the `op://` reference it
+  was typed from.
+- The API validates these rules. Request models still reject unknown members
+  and invalid shapes locally.
+
+### Use with LLM SDKs
+
+`CredentialFillTool` lets a model fill a secret or vault by name while your
+application binds the session ID. It doesn't offer 1Password fills: their
+request names the allowed origins, which a model shouldn't choose, so call
+`client.sessions.credentials.fill()` with `one_password` directly. The model chooses only `credential` or
+`vault`, the fields (`selector`, and `field` with a vault), and optionally
+`page_id`, `page_url` or `frame_url`; it never sees the values. `runnable()`
+returns JSON text for the model: the fill result, or `{"error": {"code",
+"message", "retryable", "details"}}` when the fill fails, so the model can
+react (for example by choosing a `page_id`). Give the model your other
+browser tools too, since it must submit the form itself. `async_runnable()`
+does the same with `AsyncHyperbrowser`.
+
+OpenAI (Chat Completions):
+
+```python
+import json
+
+from openai import OpenAI
+
+from hyperbrowser.tools import CredentialFillTool
+
+openai_client = OpenAI()
+tools = [CredentialFillTool.openai_tool_definition]  # plus your browser tools
+messages = [{"role": "user", "content": "Sign in to GitHub with the vault named github-login."}]
+while True:
+    response = openai_client.chat.completions.create(
+        model="gpt-5", messages=messages, tools=tools
+    )
+    message = response.choices[0].message
+    messages.append(message)
+    if not message.tool_calls:
+        break
+    for call in message.tool_calls:
+        if call.function.name == "fill_credential":
+            output = CredentialFillTool.runnable(
+                client, session.id, json.loads(call.function.arguments)
+            )
+        else:
+            output = run_browser_tool(call)  # your click/press/navigate tools
+        messages.append({"role": "tool", "tool_call_id": call.id, "content": output})
+```
+
+Anthropic (Messages):
+
+```python
+import anthropic
+
+from hyperbrowser.tools import CredentialFillTool
+
+anthropic_client = anthropic.Anthropic()
+tools = [CredentialFillTool.anthropic_tool_definition]  # plus your browser tools
+messages = [{"role": "user", "content": "Sign in to GitHub with the vault named github-login."}]
+while True:
+    response = anthropic_client.messages.create(
+        model="claude-sonnet-5-5", max_tokens=1024, tools=tools, messages=messages
+    )
+    messages.append({"role": "assistant", "content": response.content})
+    if response.stop_reason != "tool_use":
+        break
+    results = []
+    for block in response.content:
+        if block.type != "tool_use":
+            continue
+        if block.name == "fill_credential":
+            output = CredentialFillTool.runnable(client, session.id, block.input)
+        else:
+            output = run_browser_tool(block)
+        results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
+    messages.append({"role": "user", "content": results})
+```
+
+Gemini (google-genai):
+
+```python
+from google import genai
+from google.genai import types
+
+from hyperbrowser.tools import CredentialFillTool
+
+gemini = genai.Client()
+config = types.GenerateContentConfig(
+    tools=[
+        types.Tool(function_declarations=[CredentialFillTool.gemini_tool_definition])
+    ]  # plus your browser tools
+)
+contents = [
+    types.Content(
+        role="user",
+        parts=[types.Part.from_text(text="Sign in to GitHub with the vault named github-login.")],
+    )
+]
+while True:
+    response = gemini.models.generate_content(
+        model="gemini-3.5-flash", contents=contents, config=config
+    )
+    contents.append(response.candidates[0].content)
+    if not response.function_calls:
+        break
+    parts = []
+    for call in response.function_calls:
+        if call.name == "fill_credential":
+            output = CredentialFillTool.runnable(client, session.id, call.args or {})
+        else:
+            output = run_browser_tool(call)
+        parts.append(
+            types.Part.from_function_response(name=call.name, response={"result": output})
+        )
+    contents.append(types.Content(role="user", parts=parts))
+```
+
+## Tools for LLM function calling
+
+`hyperbrowser.tools` has ready-made tools: `WebsiteScrapeTool`,
+`WebsiteScreenshotTool`, `WebsiteCrawlTool`, `WebsiteExtractTool`,
+`BrowserUseTool` and `CredentialFillTool`. Each has `openai_tool_definition`
+(a strict Chat Completions function tool), `anthropic_tool_definition`, and
+`runnable()` / `async_runnable()` to run the model's input and return text for
+the model. `CredentialFillTool` also provides `gemini_tool_definition`, a
+function declaration dict for google-genai.
+
+## Usage
+
+Hyperbrowser 1.0 accepts plain dictionaries for request parameters. Method
+signatures use `TypedDict` definitions, so editors can autocomplete keys at
+every nested level:
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+# Preferred in 1.0: autocomplete works directly in the dictionary.
+session = client.sessions.create(
+    {
+        "use_stealth": True,
+        "screen": {"width": 1920, "height": 1080},
+    }
+)
+```
+
+Browser sessions can also use an outbound network policy. Omitting these fields
+keeps the default unrestricted behavior:
+
+```python
+session = client.sessions.create(
+    {
+        "allow_internet_access": False,
+        "allow_out": ["example.com"],
+        "deny_out": ["0.0.0.0/0"],
+    }
+)
+```
+
+Direct browser policies accept domains, IPv4 addresses, and CIDR ranges in
+`allow_out`; `deny_out` accepts IPv4 addresses and CIDR ranges. With a proxy,
+allow rules must be domains and the only supported deny rule is `0.0.0.0/0`.
+
+Existing Pydantic request classes remain accepted, so upgrading does not require
+an immediate rewrite:
+
+```python
+from hyperbrowser.models import CreateSessionParams, ScreenConfig
+
+session = client.sessions.create(
+    CreateSessionParams(
+        use_stealth=True,
+        screen=ScreenConfig(width=1920, height=1080),
+    )
+)
+```
+
+Import request annotations from `hyperbrowser.types` when a named variable is
+useful. The same names under `hyperbrowser.models` refer to the legacy Pydantic
+request classes. Responses remain Pydantic models.
+
+JSON Schema fields accept raw schema values, including object schemas with
+`$defs`, `$ref`, or custom keywords, and boolean schemas where the API supports
+them. Those schemas and other user-owned mappings are preserved as data; only
+SDK-owned request keys are translated to their API aliases. Schema fields
+documented as accepting a model class can also generate a schema from a Pydantic
+model.
+
+See the
+[Hyperbrowser Python SDK 1.0 migration guide](https://hyperbrowser.ai/docs/sdks/python-1-0-migration)
+for the complete compatibility details and migration checklist.
+
+### Async
+
+```python
+import asyncio
+from hyperbrowser import AsyncHyperbrowser
+from playwright.async_api import async_playwright
+
+HYPERBROWSER_API_KEY = "test-key"
+
+async def main():
+    async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+        session = await client.sessions.create()
+
+        try:
+            async with async_playwright() as playwright:
+                browser = await playwright.chromium.connect_over_cdp(
+                    session.ws_endpoint
+                )
+                context = browser.contexts[0]
+                page = context.pages[0]
+
+                print("Navigating to Hacker News...")
+                await page.goto("https://news.ycombinator.com/")
+                print("Page title:", await page.title())
+        finally:
+            await client.sessions.stop(session.id)
+
+# Run the asyncio event loop
+asyncio.run(main())
+```
+### Sync
+
+```python
+from playwright.sync_api import sync_playwright
+from hyperbrowser import Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+def main():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    session = client.sessions.create()
+
+    ws_endpoint = session.ws_endpoint
+
+    # Launch Playwright and connect to the remote browser
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(ws_endpoint)
+        context = browser.new_context()
+        
+        # Get the first page or create a new one
+        if len(context.pages) == 0:
+            page = context.new_page()
+        else:
+            page = context.pages[0]
+        
+        # Navigate to a website
+        print("Navigating to Hacker News...")
+        page.goto("https://news.ycombinator.com/")
+        page_title = page.title()
+        print("Page title:", page_title)
+        
+        page.close()
+        browser.close()
+        print("Session completed!")
+    client.sessions.stop(session.id)
+
+# Run the asyncio event loop
+main()
+```
+
+## Sandboxes
+
+The sync and async clients expose the same sandbox APIs through `client.sandboxes`.
+
+### Create a sandbox with pre-exposed ports
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(
+    {
+        "image_name": "node",
+        "cpu": 2,
+        "memory_mib": 2048,
+        "disk_mib": 8192,
+        "exposed_ports": [{"port": 3000, "auth": True}],
+    }
+)
+
+print(sandbox.exposed_ports[0].browser_url)
+print(sandbox.cpu, sandbox.memory_mib, sandbox.disk_mib)
+sandbox.stop()
+client.close()
+```
+
+`cpu`, `memory_mib`, and `disk_mib` are only supported for image launches.
+
+### Manage volumes and mount them in a sandbox
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+volume = client.volumes.create({"name": "project-cache"})
+all_volumes = client.volumes.list()
+same_volume = client.volumes.get(volume.id)
+
+sandbox = client.sandboxes.create(
+    {
+        "image_name": "node",
+        "mounts": {
+            "/workspace/cache": {
+                "id": same_volume.id,
+                "type": "rw",
+                "shared": True,
+            }
+        },
+    }
+)
+
+sandbox.stop()
+client.volumes.delete(same_volume.id)
+client.close()
+```
+
+### Manage secrets and pass them to sandbox processes
+
+Secrets hold values such as API keys for sandbox processes. Values are
+encrypted on your machine to the platform's public key before upload, and the
+API never returns them. Methods that take a secret accept its ID or exact name.
+
+```python
+from pathlib import Path
+
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+# Values are str or bytes and are stored byte-for-byte, trailing newlines included.
+client.secrets.create(
+    {
+        "name": "provider-key",
+        "description": "Provider API key",
+        "value": Path("provider-key.txt").read_bytes(),
+    }
+)
+client.secrets.add_version("provider-key", "rotated-value")  # becomes version 2
+detail = client.secrets.get("provider-key")  # metadata and versions, never the value
+client.secrets.list({"search": "provider"})
+
+# A vault groups variables; sandboxes and processes take it by name.
+client.vaults.create(
+    {"name": "app-env", "entries": {"API_KEY": {"name": "provider-key"}}}
+)
+
+sandbox = client.sandboxes.create(
+    {
+        "image_name": "node",
+        # Delivered to the image's startup command (image launches only).
+        "vault": "app-env",
+    }
+)
+print(sandbox.startup_secrets)  # what each variable received, never values
+
+# A plain name uses the latest version; {"name": ..., "version": N} pins one.
+# `secrets` are merged over the vault's entries and win on a clash.
+result = sandbox.exec(
+    "node app.js",
+    vault="app-env",
+    secrets={"API_KEY": {"name": "provider-key", "version": 2}},
+)
+process = sandbox.processes.start("node worker.js", secrets={"API_KEY": "provider-key"})
+print(process.secrets)  # the version each variable received
+
+client.vaults.delete("app-env")
+client.secrets.delete_version("provider-key", 1)
+client.secrets.delete("provider-key")
+client.close()
+```
+
+Values can also come straight from a 1Password vault. Store a 1Password
+service account token (it starts with `ops_`) as an `op_token` secret: it is
+only used to sign in to 1Password, never set as a variable or typed into a
+browser itself, and can't have allowed origins. Browser sessions can fill
+1Password fields too; see [Fill from 1Password](#fill-from-1password). Then name the fields each variable
+takes with `one_password` when creating a sandbox or starting a process.
+Nothing about them is stored: the sandbox reads the fields when the process
+starts.
+
+```python
+client.secrets.create(
+    {"name": "op-token", "type": "op_token", "value": Path("op-token.txt").read_text().strip()}
+)
+one_password = {
+    "token": "op-token",  # the op_token secret's name; its latest version signs in
+    "vault": "Engineering",  # the 1Password vault's name or ID
+    # Items, sections and fields by name or ID: op://Engineering/Postgres/prod/password
+    "fields": {
+        "DB_PASS": {"item": "Postgres", "section": "prod", "field": "password"},
+        "DB_OTP": {"item": "Postgres", "field": "one-time password?attribute=totp"},
+    },
+}
+
+# Delivered to the image's startup command (image launches only).
+sandbox = client.sandboxes.create({"image_name": "node", "one_password": one_password})
+print(sandbox.startup_secrets)  # each with its op:// reference and token_secret
+
+result = sandbox.exec("psql -c 'select 1'", one_password=one_password)
+process = sandbox.processes.start("node worker.js", one_password=one_password)
+print(process.secrets)  # source.type is "onePassword" for these variables
+```
+
+`one_password` takes one token and vault per request and 1-32 fields, named
+like environment variables. A field may end with a query such as
+`?attribute=otp`, `?attribute=totp` or `?ssh-format=openssh`. Vaults, items,
+sections and fields are 1-256 characters (UTF-16 code units) without `/`, `?` or control characters, and
+not `.` or `..`; the whole `op://` reference is at most 512 bytes. These are
+checked by the API, as is a variable that `secrets`, `env` or the request's
+`vault` also sets: a variable from 1Password must come from it alone.
+
+Things to know:
+
+- A secret is set only in the environment of the process it was passed to.
+  Anything else running as the same user, or as root, in the sandbox can read
+  that environment.
+- A sandbox that has received secrets, and snapshots taken of it, report
+  `contains_secrets=True`. Restoring such a snapshot needs the same access as
+  passing secrets.
+- Deleting a secret or version doesn't revoke a value already delivered to a
+  sandbox.
+- Limits: 100 secrets per team, 10 versions per secret, 32 secrets per process,
+  and values of 1 byte to 32 KiB of UTF-8 without NUL bytes. Names are 1-128
+  letters, digits, `_` or `-`, starting with a letter or digit.
+- Reading secrets needs `secrets.read`; delivering them to a sandbox needs
+  `secrets.use`. Creating a secret needs `secrets.manage`. Updating, rotating,
+  and deleting secrets or versions through the SDK need both `secrets.read`
+  and `secrets.manage`, since it resolves IDs and names through metadata reads.
+  `add_version()` also reads the secret's `encryptionContext` to encrypt its
+  value. The team needs the secrets feature.
+- Secret-started process handles wait indefinitely by default with `wait()` or
+  `result()`. A positive `wait(timeout_ms=...)` or `wait(timeout_sec=...)` limits
+  the total local wait and raises `TimeoutError` (`asyncio.TimeoutError` for
+  async handles); the process continues and the handle can be used to wait
+  again. The start's timeout limits the command's execution separately.
+  The sync client checks the limit between requests and caps each request's
+  HTTP timeouts at the time left, so a slow response or a runtime token
+  refresh can overrun it; use the async client for a strict limit.
+  Secret process output comes from the receiver's retained output, so
+  `max_output_bytes` does not apply; incomplete retained output raises an error.
+- A process start with secrets that times out, or whose result the API can't
+  confirm, raises a non-retryable error with code
+  `secret_process_outcome_unknown`: the command may be running, so check
+  `sandbox.processes.list()` before retrying. When the API reported the
+  unknown outcome itself, its response body, including its own code
+  (`SECRET_PROCESS_OUTCOME_UNKNOWN`), is in the error's `details`.
+- `client.sandboxes.create()` with `secrets`, `vault` or `one_password`
+  raises the same
+  `secret_process_outcome_unknown` error when the create may have reached the
+  API but its result is unknown (a timeout, a dropped connection, or an
+  unreadable response): a sandbox may be running its startup command with the
+  secrets, so list sandboxes before retrying.
+- Vaults hold up to 32 stored secrets, named like environment variables; a
+  team has up to 100. Methods that take a vault accept its ID or exact name,
+  and vaults need the same scopes as secrets. A vault, `secrets` and
+  `one_password` together deliver at most 32 variables, and a process's `env`
+  may not set one of them.
+- Error codes from the API:
+  - `SECRETS_ADMIN_REQUIRED` (403): the request used an `hx auth login`
+    session of a team member who isn't an owner or admin. API keys are
+    governed by their scopes instead.
+  - `SECRETS_FEATURE_DISABLED` (403): the team doesn't have the secrets
+    feature.
+  - `SECRETS_NOT_CONFIGURED` (503): the platform has no secrets key
+    configured. It isn't retried.
+  - `SECRET_STARTUP_UNSUPPORTED` (400): the image has no startup command to
+    deliver `secrets`, a `vault` or `one_password` to. Create the sandbox without them, then pass them to
+    `sandbox.exec()` or `sandbox.processes.start()`.
+  - `VAULT_NOT_FOUND` (404), `VAULT_NAME_TAKEN`, `VAULT_LIMIT_REACHED`,
+    `VAULT_ENTRY_LIMIT_REACHED` (409).
+  - `SECRET_IN_USE` (409): a vault uses the secret as an entry;
+    `SECRET_VERSION_IN_USE` (409): a vault pins the version. Only vaults
+    hold secrets, so an `op_token` can always be deleted.
+  - `SECRET_TYPE_MISMATCH` (409): an `op_token` used as a variable or vault
+    entry, or another type named as `one_password`'s `token`.
+  - `SECRET_SOURCES_INVALID` (400): for example `env` sets a variable that
+    `vault` or `secrets` also sets, a `one_password` variable is also set by
+    `vault`, `secrets` or `env`, or the sources deliver more than 32
+    variables.
+  - `SECRET_VALUE_INVALID` (422): a stored value is unusable, such as a bad
+    TOTP seed; fix it by adding a new version.
+  - `SECRET_TOTP_UNSUPPORTED` and `SECRET_ONEPASSWORD_UNSUPPORTED` (501): the
+    sandbox's host predates TOTP or 1Password, so nothing started. Retryable
+    on sandbox create, which may land on a newer host; not on a process start.
+  - `SECRET_ONEPASSWORD_REFERENCE_FAILED` (422, `details` names the
+    variables) and `SECRET_ONEPASSWORD_AUTH_FAILED` (422, also a malformed
+    token, or one that doesn't sign in to `1password.com`, `.ca` or `.eu`,
+    which is never sent to 1Password): fix the fields or the token.
+    `SECRET_ONEPASSWORD_RATE_LIMITED` (429) and
+    `SECRET_ONEPASSWORD_FAILED` (502/503) are retryable.
+  - `retryable` is the API's flag when it sends one.
+
+### List sandboxes with filters
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+result = client.sandboxes.list(
+    {
+        "status": "active",
+        "search": "sandbox",
+        "start": 1711929600000,
+        "end": 1712016000000,
+        "limit": 20,
+    }
+)
+
+for sandbox in result.sandboxes:
+    print(sandbox.id, sandbox.status)
+```
+
+### List snapshots for a specific image
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+snapshots = client.sandboxes.list_snapshots(
+    {"image_name": "node", "status": "created", "limit": 10}
+)
+```
+
+### Expose and unexpose ports
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(
+    {"image_name": "node", "cpu": 2, "memory_mib": 2048, "disk_mib": 8192}
+)
+
+result = sandbox.expose({"port": 8080, "auth": True})
+print(result.url, result.browser_url)
+
+sandbox.unexpose(8080)
+```
+
+### Batch file writes with per-file options
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create({"image_name": "node"})
+
+sandbox.files.write(
+    [
+        {
+            "path": "/tmp/config.json",
+            "data": '{"debug":true}\n',
+            "append": True,
+            "mode": "600",
+        },
+        {"path": "/tmp/blob.bin", "data": b"\x00\x01\x02"},
+    ]
+)
+```
+
+### Run commands and collect output
+
+`sandbox.exec()` and `sandbox.processes.start()` stream command output from the
+receiver as soon as execution starts. The SDK collects stdout and stderr in
+memory, so a completed result is not limited to the receiver's replay buffer.
+This requires a receiver supporting streaming `POST /sandbox/processes`; roll
+out the receiver before upgrading the SDK.
+
+```python
+result = sandbox.exec("make test", max_output_bytes=128 * 1024 * 1024)
+print(result.stdout, result.stderr, result.exit_code)
+
+process = sandbox.processes.start("make test")
+try:
+    for event in process.stream():
+        if event.type == "stdout":
+            print(event.data, end="")
+    result = process.wait()
+finally:
+    process.disconnect()
+```
+
+The combined output limit defaults to 64 MiB per command and can be adjusted
+with `max_output_bytes`. Exceeding it raises `output_limit_exceeded`. A broken
+stream, missing output, or receiver truncation raises `incomplete_output`.
+These errors include the process ID and do not automatically rerun the command.
+
+Process streams use a separate 60-second read-idle timeout once response headers
+arrive. Output and the receiver's 15-second heartbeats reset this timeout, so quiet
+commands can run longer than the client's ordinary HTTP timeout. That ordinary
+timeout still applies to connection setup and waiting for response headers.
+
+`start()` returns after the process starts and collects in the background.
+`wait(timeout_sec=...)` limits the local wait; collection continues after a wait
+timeout. The timeout passed to `start()` or `exec()` limits command execution.
+A local wait timeout raises `TimeoutError` (`asyncio.TimeoutError` in the async API).
+`disconnect()` stops collection and leaves the command running. Use `kill()` to
+stop it. Reattaching with `get()` can retrieve only retained receiver output;
+`wait()` raises if that output has been truncated.
+
+The async API has the same behavior: await `exec()`, `start()`, `wait()`, and
+`disconnect()`, and use `async for` with `stream()`.
+
+### Resume terminal output after reconnect
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create({"image_name": "node"})
+terminal = sandbox.terminal.create({"command": "bash"})
+
+connection = terminal.attach(cursor=10)
+for event in connection.events():
+    print(event)
+```
+
+### Cache remote Dockerfile builds
+
+Use the public context fingerprint when deriving a cache name. It uses the same
+Dockerfile source selection and `.dockerignore` rules as remote packaging,
+including file contents, modes, paths, and symlinks. It ignores timestamps and
+does not compress or stage the context on disk.
+
+```python
+from hyperbrowser.build_context import docker_build_context_fingerprint
+
+fingerprint = docker_build_context_fingerprint("./app")
+# Include build options such as platform and image_init in your cache key too.
+image_name = f"app-{fingerprint[:32]}"
+build = client.sandboxes.build_image_from_dockerfile(
+    context_path="./app",
+    image_name=image_name,
+    expected_context_fingerprint=fingerprint,
+)
+```
+
+If the archived inputs differ from the fingerprint, the SDK raises
+`DockerBuildContextChangedError` before creating or uploading a build. Compute a
+fresh fingerprint and repeat the lookup/build operation. Use the same `dockerfile`
+and `force_full_context` selection when fingerprinting and building (the latter
+is named `remote_full_context` on the build method). The expected fingerprint is
+supported only for remote builds.
+
+Fingerprinting streams included files and performs blocking I/O. Async callers
+should use `await asyncio.to_thread(docker_build_context_fingerprint, "./app")`
+(Python 3.9+) or an executor. It does not resolve mutable base-image tags or
+network resources fetched by a Dockerfile; rebuild explicitly when those change.
+
+Image listings distinguish `ready` from `uploaded`: a completed team image can
+be ready to launch before its durability backup is uploaded. `ready` is `None`
+when talking to an older server. Keep the returned image ID to pin that revision.
+
+### Reuse an image or join a build
+
+`get_or_build_image` provides the same operation on sync and async clients. Give
+it either a remote Dockerfile context or a local Docker image. It derives a name
+from the input identity and image initialization options, reuses a ready team
+image, or submits a build and joins a compatible concurrent build automatically.
+The optional prefix is a namespace, not a fixed image alias: different inputs
+produce different names under the same prefix.
+
+```python
+resolved = client.sandboxes.get_or_build_image(
+    context_path="./app",  # alternatively: docker_image="local/app:latest"
+    image_name_prefix="my-app",
+    wait_timeout=3600,
+)
+print(resolved.outcome)  # "reused", "joined", or "created"
+sandbox = client.sandboxes.create({
+    "image_name": resolved.image_name,
+    "image_id": resolved.image_id,
+})
+```
+
+With `wait=False`, a submitted/joined build is returned as `resolved.build`;
+`image_id` is populated only when ready. `find_ready_image(name)` exposes the
+exact-name lookup separately. Older servers fall back to uploaded-image reuse.
+The public `hyperbrowser.image_builds.image_build_name` helper lets integrations
+derive the same name from an existing context fingerprint or Docker image digest.
+Passing `expected_context_fingerprint` or `expected_image_digest` avoids repeating
+identity discovery; supply a fresh identity for each resolution request. Changes
+between identity discovery and packaging are rejected instead of published under
+the wrong name. Local Docker images must already be available in the daemon.
+
+Automatic local-image identity discovery requires a Docker CLI and Engine
+supporting **API 1.49 or newer (Docker 28.1+)** for platform-specific inspection.
+Upgrade Docker and check for an older `DOCKER_API_VERSION` override if the helper
+reports this requirement. Remote Dockerfile builds do not require local Docker.
+The existing explicit-name import method retains its inspection fallback.
+
+`force_build=True` skips ready-image lookup but still joins matching active builds
+and permits existing layer/artifact caches. Use it to refresh mutable base tags or
+external Dockerfile downloads. Joining does not change an existing builder's
+resources. Lookup and creation use separate API calls; if another build completes
+between them, an additional revision can be submitted.
+
+Each caller owns its polling timeout. Canceling that wait does not cancel an
+accepted backend build. Uploads have a separate inactivity allowance
+(`upload_timeout=600` by default), not a total upload-duration limit. The existing
+`build_image_from_dockerfile` and `build_image_from_docker_image` methods retain
+their explicit-name behavior and continue to report build conflicts directly.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+