hyperbrowser 1.10.0__tar.gz → 1.11.1__tar.gz

{hyperbrowser-1.10.0 → hyperbrowser-1.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.10.0
+Version: 1.11.1
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -17,6 +17,7 @@ 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)
@@ -62,6 +63,40 @@ 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.
+
 ## Usage
 
 Hyperbrowser 1.0 accepts plain dictionaries for request parameters. Method
@@ -255,6 +290,104 @@ 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"})
+
+sandbox = client.sandboxes.create(
+    {
+        "image_name": "node",
+        # Delivered to the image's startup command (image launches only).
+        "secrets": {"API_KEY": "provider-key"},
+    }
+)
+
+# A plain name uses the latest version; {"name": ..., "version": N} pins one.
+result = sandbox.exec(
+    "node app.js",
+    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.secrets.delete_version("provider-key", 1)
+client.secrets.delete("provider-key")
+client.close()
+```
+
+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` 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.
+- 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` to. Create the sandbox without them, then pass them to
+    `sandbox.exec()` or `sandbox.processes.start()`.
+
 ### List sandboxes with filters
 
 ```python

{hyperbrowser-1.10.0 → hyperbrowser-1.11.1}/README.md

@@ -34,6 +34,40 @@ 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.
+
 ## Usage
 
 Hyperbrowser 1.0 accepts plain dictionaries for request parameters. Method
@@ -227,6 +261,104 @@ 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"})
+
+sandbox = client.sandboxes.create(
+    {
+        "image_name": "node",
+        # Delivered to the image's startup command (image launches only).
+        "secrets": {"API_KEY": "provider-key"},
+    }
+)
+
+# A plain name uses the latest version; {"name": ..., "version": N} pins one.
+result = sandbox.exec(
+    "node app.js",
+    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.secrets.delete_version("provider-key", 1)
+client.secrets.delete("provider-key")
+client.close()
+```
+
+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` 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.
+- 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` to. Create the sandbox without them, then pass them to
+    `sandbox.exec()` or `sandbox.processes.start()`.
+
 ### List sandboxes with filters
 
 ```python

{hyperbrowser-1.10.0 → hyperbrowser-1.11.1}/hyperbrowser/client/async_client.py

@@ -10,6 +10,7 @@ from .managers.async_manager.extension import ExtensionManager
 from .managers.async_manager.extract import ExtractManager
 from .managers.async_manager.profile import ProfileManager
 from .managers.async_manager.sandbox import SandboxManager
+from .managers.async_manager.secret import SecretManager
 from .managers.async_manager.scrape import ScrapeManager
 from .managers.async_manager.session import SessionManager
 from .managers.async_manager.team import TeamManager
@@ -49,6 +50,7 @@ class AsyncHyperbrowser(HyperbrowserBase):
         self.computer_action = ComputerActionManager(self)
         self.sandboxes = SandboxManager(self)
         self.volumes = VolumeManager(self)
+        self.secrets = SecretManager(self)
 
     async def close(self) -> None:
         await self.transport.close()

{hyperbrowser-1.10.0 → hyperbrowser-1.11.1}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -41,6 +41,13 @@ from ....models.sandbox import (
     StartSandboxFromSnapshotParams,
 )
 from ....models.session import BasicResponse
+from ....secrets_common import (
+    missing_process_id_error,
+    request_may_have_arrived,
+    sandbox_create_outcome_unknown_error,
+    secret_process_id,
+    secret_process_start_error,
+)
 from ....types import (
     CompleteSandboxImageBuildParams as CompleteSandboxImageBuildParamsDict,
     CreateSandboxImageBuildParams as CreateSandboxImageBuildParamsDict,
@@ -72,6 +79,7 @@ from ..sandboxes.image_resolution import (
     completed_image_id,
 )
 from ..sandboxes.shared import (
+    SecretReferences,
     _build_sandbox_exposed_url,
     _copy_model,
     _expires_within_buffer,
@@ -143,7 +151,11 @@ class SandboxHandle:
             service.runtime_timeout,
             service.runtime_proxy_override,
         )
-        self.processes = SandboxProcessesApi(self._transport)
+        self.processes = SandboxProcessesApi(
+            self._transport,
+            self._start_secret_process,
+            detail.id,
+        )
         self.files = SandboxFilesApi(
             self._transport,
             self._resolve_runtime_socket_info,
@@ -318,7 +330,16 @@ class SandboxHandle:
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
         max_output_bytes: int = 64 * 1024 * 1024,
+        secrets: Optional[SecretReferences] = None,
     ):
+        """Run a command to completion.
+
+        ``secrets`` maps environment variable names to stored secrets (a name,
+        or ``{"name": ..., "version": N}``). Anything else running as the
+        same user, or as root, in the sandbox can read a process's
+        environment, and the sandbox and its later snapshots are marked as
+        containing secrets.
+        """
         return await self.processes.exec(
             input,
             cwd=cwd,
@@ -327,8 +348,12 @@ class SandboxHandle:
             timeout_sec=timeout_sec,
             run_as=run_as,
             max_output_bytes=max_output_bytes,
+            secrets=secrets,
         )
 
+    async def _start_secret_process(self, payload: Dict[str, object]) -> dict:
+        return await self._service.start_secret_process(self.id, payload)
+
     async def get_process(self, process_id: str) -> SandboxProcessHandle:
         return await self.processes.get(process_id)
 
@@ -1127,16 +1152,44 @@ class SandboxManager:
         )
         return SandboxUnexposeResult(**payload)
 
+    async def start_secret_process(
+        self, sandbox_id: str, payload: Dict[str, object]
+    ) -> dict:
+        """Start a sandbox process with secrets through the control API.
+
+        Returns the raw ``{"process": ..., "secrets": [...]}`` response. Prefer
+        ``sandbox.exec(..., secrets=...)`` or ``sandbox.processes.start``.
+        """
+        try:
+            response = await self._request(
+                "POST", f"/sandbox/{sandbox_id}/processes", data=payload
+            )
+        except HyperbrowserError as error:
+            raise secret_process_start_error(sandbox_id, error)
+        process = response.get("process") if isinstance(response, dict) else None
+        process_id = secret_process_id(process)
+        if not process_id:
+            raise missing_process_id_error(sandbox_id)
+        return dict(response, process=dict(process, id=process_id))
+
     async def _create_detail(
         self,
         params: Union[CreateSandboxParamsDict, CreateSandboxParams],
     ) -> SandboxDetail:
-        payload = await self._request(
-            "POST",
-            "/sandbox",
-            data=dump_request(params, CreateSandboxParams),
-        )
-        return SandboxDetail(**payload)
+        normalized = coerce_request(params, CreateSandboxParams)
+        data = dump_request(normalized, CreateSandboxParams)
+        try:
+            payload = await self._request("POST", "/sandbox", data=data)
+            detail = SandboxDetail(**payload)
+            if normalized.secrets and not detail.id.strip():
+                raise ValueError("The API accepted the create but returned no sandbox ID")
+            return detail
+        except Exception as error:
+            # A create that may have reached the API may be running its
+            # startup command with the secrets, so it must not look retryable.
+            if normalized.secrets and request_may_have_arrived(error):
+                raise sandbox_create_outcome_unknown_error(error)
+            raise
 
     async def _request(
         self,

{hyperbrowser-1.10.0 → hyperbrowser-1.11.1}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_processes.py

@@ -1,8 +1,9 @@
 import asyncio
 import base64
-from typing import AsyncIterator, Dict, Optional, Union
+import time
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, List, Optional, Union
 
-from ...._request import coerce_request, dump_request
+from ...._request import coerce_request
 from .....models.sandbox import (
     SandboxExecParams,
     SandboxProcessExitEvent,
@@ -12,11 +13,24 @@ from .....models.sandbox import (
     SandboxProcessStdinParams,
     SandboxProcessSummary,
 )
+from .....exceptions import HyperbrowserError
+from .....models.secret import SandboxResolvedSecret
+from .....secrets_common import (
+    SecretProcessWait,
+    SecretProcessWaitContext,
+    secret_process_failed_error,
+    secret_process_id,
+)
 from .....types import (
     SandboxExecParams as SandboxExecParamsDict,
     SandboxProcessStdinParams as SandboxProcessStdinParamsDict,
 )
-from ...sandboxes.shared import _normalize_exec_params
+from ...sandboxes.shared import (
+    SecretReferences,
+    _normalize_exec_params,
+    _runtime_process_payload,
+    _secret_process_payload,
+)
 from ...sandboxes.process_output import (
     DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
     ProcessOutput,
@@ -28,13 +42,22 @@ DEFAULT_PROCESS_KILL_WAIT_SECONDS = 5.0
 
 
 class SandboxProcessHandle:
-    def __init__(self, transport: RuntimeTransport, summary: SandboxProcessSummary):
+    def __init__(
+        self,
+        transport: RuntimeTransport,
+        summary: SandboxProcessSummary,
+        secret_wait_context: Optional[SecretProcessWaitContext] = None,
+    ):
         self._transport = transport
         self._summary = summary
+        self._secret_wait_context = secret_wait_context
         self._output = None
         self._collector = None
         self._events = None
         self._changed = asyncio.Event()
+        # The secret versions this process received, when it was started
+        # with secrets; None otherwise.
+        self.secrets: Optional[List[SandboxResolvedSecret]] = None
 
     @property
     def id(self) -> str:
@@ -69,6 +92,53 @@ class SandboxProcessHandle:
             if not self._collector.done():
                 await asyncio.wait_for(asyncio.shield(self._collector), timeout)
             return self._collected_result()
+        if self._secret_wait_context is not None:
+            return await self._wait_with_secrets(timeout_ms, timeout_sec)
+        return await self._wait_once(timeout_ms, timeout_sec)
+
+    async def _wait_with_secrets(
+        self, timeout_ms: Optional[int], timeout_sec: Optional[int]
+    ) -> SandboxProcessResult:
+        context = self._secret_wait_context
+        assert context is not None
+        wait = SecretProcessWait(
+            context, timeout_ms, timeout_sec, timeout_error=asyncio.TimeoutError
+        )
+        while True:
+            chunk_ms, request_timeout, remaining = wait.request_budget()
+            started_at = time.monotonic()
+            try:
+                request = self._wait_once(chunk_ms, None, request_timeout)
+                result = await asyncio.wait_for(request, remaining)
+                wait.remaining()
+                return result
+            except (TimeoutError, asyncio.TimeoutError) as error:
+                if wait.deadline is not None:
+                    raise asyncio.TimeoutError(
+                        "Timed out waiting for command output"
+                    ) from error
+                raise secret_process_failed_error(
+                    context.sandbox_id, self.id, "waiting for its result", error
+                )
+            except Exception as error:
+                # An explicit local deadline keeps TimeoutError semantics. It
+                # ends only this wait; callers can wait again on the handle.
+                wait.remaining()
+                if not isinstance(error, HyperbrowserError) or error.status_code != 408:
+                    raise secret_process_failed_error(
+                        context.sandbox_id, self.id, "waiting for its result", error
+                    )
+            await asyncio.sleep(wait.retry_delay(started_at))
+
+    async def _wait_once(
+        self,
+        timeout_ms: Optional[int],
+        timeout_sec: Optional[int],
+        request_timeout: Optional[float] = None,
+    ) -> SandboxProcessResult:
+        request_options: Dict[str, Any] = {}
+        if request_timeout is not None:
+            request_options["request_timeout"] = request_timeout
         payload = await self._transport.request_json(
             f"/sandbox/processes/{self.id}/wait",
             method="POST",
@@ -77,6 +147,7 @@ class SandboxProcessHandle:
                 "timeout_sec": timeout_sec,
             },
             headers={"content-type": "application/json"},
+            **request_options,
         )
         result = SandboxProcessResult(**payload["result"])
         if result.output_truncated:
@@ -260,8 +331,17 @@ class SandboxProcessHandle:
 
 
 class SandboxProcessesApi:
-    def __init__(self, transport: RuntimeTransport):
+    def __init__(
+        self,
+        transport: RuntimeTransport,
+        start_secret_process: Optional[
+            Callable[[Dict[str, object]], Awaitable[dict]]
+        ] = None,
+        sandbox_id: Optional[str] = None,
+    ):
         self._transport = transport
+        self._start_secret_process = start_secret_process
+        self._sandbox_id = sandbox_id
 
     async def exec(
         self,
@@ -273,6 +353,7 @@ class SandboxProcessesApi:
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
         max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
+        secrets: Optional[SecretReferences] = None,
     ) -> SandboxProcessResult:
         handle = await self.start(
             input,
@@ -282,7 +363,10 @@ class SandboxProcessesApi:
             timeout_sec=timeout_sec,
             run_as=run_as,
             max_output_bytes=max_output_bytes,
+            secrets=secrets,
         )
+        if handle.secrets is not None:
+            return await self._finish_secret_exec(handle)
         try:
             return await handle.wait()
         finally:
@@ -298,7 +382,14 @@ class SandboxProcessesApi:
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
         max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
+        secrets: Optional[SecretReferences] = None,
     ) -> SandboxProcessHandle:
+        """Start a process.
+
+        With ``secrets``, the start goes through the control API, which has the
+        platform decrypt them into the process environment; output is then
+        read with ``wait()`` rather than collected from the start.
+        """
         validate_output_limit(max_output_bytes)
         params = _normalize_exec_params(
             input,
@@ -307,11 +398,14 @@ class SandboxProcessesApi:
             timeout_ms=timeout_ms,
             timeout_sec=timeout_sec,
             run_as=run_as,
+            secrets=secrets,
         )
+        if params.secrets:
+            return await self._start_with_secrets(params)
         events = self._transport.stream_sse(
             "/sandbox/processes",
             method="POST",
-            json_body=dump_request(params, SandboxExecParams),
+            json_body=_runtime_process_payload(params),
         )
         try:
             started = await events.__anext__()
@@ -328,6 +422,58 @@ class SandboxProcessesApi:
         handle._collector = asyncio.create_task(handle._collect())
         return handle
 
+    async def _start_with_secrets(
+        self, params: SandboxExecParams
+    ) -> SandboxProcessHandle:
+        if self._start_secret_process is None:
+            raise HyperbrowserError(
+                "Starting a process with secrets needs a sandbox handle; use "
+                "client.sandboxes.get() and its processes API",
+                code="secrets_unsupported",
+            )
+        payload = await self._start_secret_process(_secret_process_payload(params))
+        process_id = secret_process_id(payload["process"])
+        try:
+            handle = SandboxProcessHandle(
+                self._transport,
+                SandboxProcessSummary(**dict(payload["process"], id=process_id)),
+                SecretProcessWaitContext(
+                    self._sandbox_id or "", getattr(self._transport, "_timeout", None)
+                ),
+            )
+            handle.secrets = [
+                SandboxResolvedSecret(**entry) for entry in payload.get("secrets") or []
+            ]
+            return handle
+        except Exception as error:
+            raise secret_process_failed_error(
+                self._sandbox_id or "", process_id, "reading its start response", error
+            )
+
+    async def _finish_secret_exec(
+        self, handle: SandboxProcessHandle
+    ) -> SandboxProcessResult:
+        """Close stdin and wait for the result, as one-shot exec does.
+
+        The process may still be running with its secrets after a failure here,
+        so failures name it instead of looking like a safe retry.
+        """
+        sandbox_id = self._sandbox_id or ""
+        try:
+            await handle.write_stdin(eof=True)
+        except HyperbrowserError as error:
+            # 409: the command already exited, like a pipe whose reader quit
+            # early. Its result is still reported.
+            if error.status_code != 409:
+                raise secret_process_failed_error(
+                    sandbox_id, handle.id, "closing its stdin", error
+                )
+        except Exception as error:
+            raise secret_process_failed_error(
+                sandbox_id, handle.id, "closing its stdin", error
+            )
+        return await handle.wait()
+
     async def get(self, process_id: str) -> SandboxProcessHandle:
         payload = await self._transport.request_json(f"/sandbox/processes/{process_id}")
         return SandboxProcessHandle(