hyperbrowser 0.90.0__tar.gz → 0.90.2__tar.gz

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 0.90.0
+Version: 0.90.2
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -156,6 +156,35 @@ 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
+from hyperbrowser.models import CreateSandboxParams, CreateVolumeParams, SandboxVolumeMount
+
+client = Hyperbrowser(api_key="test-key")
+
+volume = client.volumes.create(CreateVolumeParams(name="project-cache"))
+all_volumes = client.volumes.list()
+same_volume = client.volumes.get(volume.id)
+
+sandbox = client.sandboxes.create(
+    CreateSandboxParams(
+        image_name="node",
+        mounts={
+            "/workspace/cache": SandboxVolumeMount(
+                id=same_volume.id,
+                type="rw",
+                shared=True,
+            )
+        },
+    )
+)
+
+sandbox.stop()
+client.close()
+```
+
 ### List sandboxes with filters
 
 ```python

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/README.md

@@ -130,6 +130,35 @@ 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
+from hyperbrowser.models import CreateSandboxParams, CreateVolumeParams, SandboxVolumeMount
+
+client = Hyperbrowser(api_key="test-key")
+
+volume = client.volumes.create(CreateVolumeParams(name="project-cache"))
+all_volumes = client.volumes.list()
+same_volume = client.volumes.get(volume.id)
+
+sandbox = client.sandboxes.create(
+    CreateSandboxParams(
+        image_name="node",
+        mounts={
+            "/workspace/cache": SandboxVolumeMount(
+                id=same_volume.id,
+                type="rw",
+                shared=True,
+            )
+        },
+    )
+)
+
+sandbox.stop()
+client.close()
+```
+
 ### List sandboxes with filters
 
 ```python

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/async_client.py

@@ -14,6 +14,7 @@ from .managers.async_manager.scrape import ScrapeManager
 from .managers.async_manager.session import SessionManager
 from .managers.async_manager.team import TeamManager
 from .managers.async_manager.computer_action import ComputerActionManager
+from .managers.async_manager.volume import VolumeManager
 
 
 class AsyncHyperbrowser(HyperbrowserBase):
@@ -47,6 +48,7 @@ class AsyncHyperbrowser(HyperbrowserBase):
         self.team = TeamManager(self)
         self.computer_action = ComputerActionManager(self)
         self.sandboxes = SandboxManager(self)
+        self.volumes = VolumeManager(self)
 
     async def close(self) -> None:
         await self.transport.close()

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -217,16 +217,24 @@ class SandboxHandle:
             )
         return _copy_model(self._runtime_session)
 
-    async def exec(self, input: Union[str, SandboxExecParams]):
-        if isinstance(input, str):
-            params = SandboxExecParams(command=input)
-        else:
-            if not isinstance(input, SandboxExecParams):
-                raise TypeError(
-                    "input must be a command string or SandboxExecParams instance"
-                )
-            params = input
-        return await self.processes.exec(params)
+    async def exec(
+        self,
+        input: Union[str, SandboxExecParams],
+        *,
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+        timeout_sec: Optional[int] = None,
+        run_as: Optional[str] = None,
+    ):
+        return await self.processes.exec(
+            input,
+            cwd=cwd,
+            env=env,
+            timeout_ms=timeout_ms,
+            timeout_sec=timeout_sec,
+            run_as=run_as,
+        )
 
     async def get_process(self, process_id: str) -> SandboxProcessHandle:
         return await self.processes.get(process_id)

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_files.py

@@ -5,7 +5,7 @@ import io
 import json
 import socket
 from datetime import datetime
-from typing import AsyncIterator, Callable, List, Optional, Union
+from typing import Any, AsyncIterator, Callable, Dict, List, Optional, Union
 from urllib.parse import urlencode
 
 from websockets.asyncio.client import connect as async_ws_connect
@@ -249,10 +249,21 @@ class SandboxFilesApi:
         transport: RuntimeTransport,
         get_connection_info,
         runtime_proxy_override: Optional[str] = None,
+        default_run_as: Optional[str] = None,
     ):
         self._transport = transport
         self._get_connection_info = get_connection_info
         self._runtime_proxy_override = runtime_proxy_override
+        self._default_run_as = default_run_as.strip() if default_run_as else None
+
+    def with_run_as(self, run_as: Optional[str]):
+        normalized = run_as.strip() if run_as else None
+        return SandboxFilesApi(
+            self._transport,
+            self._get_connection_info,
+            self._runtime_proxy_override,
+            default_run_as=normalized,
+        )
 
     async def list(
         self,
@@ -266,17 +277,19 @@ class SandboxFilesApi:
 
         payload = await self._transport.request_json(
             "/sandbox/files",
-            params={
-                "path": path,
-                "depth": depth,
-            },
+            params=self._with_run_as_params(
+                {
+                    "path": path,
+                    "depth": depth,
+                }
+            ),
         )
         return [_normalize_file_info(entry) for entry in payload.get("entries", [])]
 
     async def get_info(self, path: str) -> SandboxFileInfo:
         payload = await self._transport.request_json(
             "/sandbox/files/stat",
-            params={"path": path},
+            params=self._with_run_as_params({"path": path}),
         )
         return _normalize_file_info(payload["file"])
 
@@ -357,10 +370,12 @@ class SandboxFilesApi:
             payload = await self._transport.request_json(
                 "/sandbox/files/write",
                 method="POST",
-                json_body={
-                    "path": path_or_files,
-                    **_encode_write_data(data),
-                },
+                json_body=self._with_run_as_body(
+                    {
+                        "path": path_or_files,
+                        **_encode_write_data(data),
+                    }
+                ),
                 headers={"content-type": "application/json"},
             )
             return _normalize_write_info(payload["files"][0])
@@ -377,7 +392,7 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/write",
             method="POST",
-            json_body={"files": encoded_files},
+            json_body=self._with_run_as_body({"files": encoded_files}),
             headers={"content-type": "application/json"},
         )
         return [_normalize_write_info(entry) for entry in payload.get("files", [])]
@@ -419,7 +434,7 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/upload",
             method="PUT",
-            params={"path": path},
+            params=self._with_run_as_params({"path": path}),
             content=body,
         )
         return SandboxFileTransferResult(**payload)
@@ -427,7 +442,7 @@ class SandboxFilesApi:
     async def download(self, path: str) -> bytes:
         return await self._transport.request_bytes(
             "/sandbox/files/download",
-            params={"path": path},
+            params=self._with_run_as_params({"path": path}),
         )
 
     async def make_dir(
@@ -440,11 +455,13 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/mkdir",
             method="POST",
-            json_body={
-                "path": path,
-                "parents": parents,
-                "mode": mode,
-            },
+            json_body=self._with_run_as_body(
+                {
+                    "path": path,
+                    "parents": parents,
+                    "mode": mode,
+                }
+            ),
             headers={"content-type": "application/json"},
         )
         return bool(payload.get("created"))
@@ -475,7 +492,7 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/move",
             method="POST",
-            json_body=payload,
+            json_body=self._with_run_as_body(payload),
             headers={"content-type": "application/json"},
         )
         return _normalize_file_info(payload["entry"])
@@ -493,10 +510,12 @@ class SandboxFilesApi:
         await self._transport.request_json(
             "/sandbox/files/delete",
             method="POST",
-            json_body=SandboxFileDeleteParams(
-                path=path,
-                recursive=recursive,
-            ).model_dump(exclude_none=True),
+            json_body=self._with_run_as_body(
+                SandboxFileDeleteParams(
+                    path=path,
+                    recursive=recursive,
+                ).model_dump(exclude_none=True)
+            ),
             headers={"content-type": "application/json"},
         )
 
@@ -527,12 +546,14 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/copy",
             method="POST",
-            json_body={
-                "from": normalized.source,
-                "to": normalized.destination,
-                "recursive": normalized.recursive,
-                "overwrite": normalized.overwrite,
-            },
+            json_body=self._with_run_as_body(
+                {
+                    "from": normalized.source,
+                    "to": normalized.destination,
+                    "recursive": normalized.recursive,
+                    "overwrite": normalized.overwrite,
+                }
+            ),
             headers={"content-type": "application/json"},
         )
         return _normalize_file_info(payload["entry"])
@@ -558,7 +579,7 @@ class SandboxFilesApi:
         await self._transport.request_json(
             "/sandbox/files/chmod",
             method="POST",
-            json_body=normalized.model_dump(exclude_none=True),
+            json_body=self._with_run_as_body(normalized.model_dump(exclude_none=True)),
             headers={"content-type": "application/json"},
         )
 
@@ -585,7 +606,7 @@ class SandboxFilesApi:
         await self._transport.request_json(
             "/sandbox/files/chown",
             method="POST",
-            json_body=normalized.model_dump(exclude_none=True),
+            json_body=self._with_run_as_body(normalized.model_dump(exclude_none=True)),
             headers={"content-type": "application/json"},
         )
 
@@ -593,10 +614,12 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/watch",
             method="POST",
-            json_body={
-                "path": path,
-                "recursive": recursive,
-            },
+            json_body=self._with_run_as_body(
+                {
+                    "path": path,
+                    "recursive": recursive,
+                }
+            ),
             headers={"content-type": "application/json"},
         )
         return SandboxFileWatchHandle(
@@ -646,11 +669,13 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/presign-upload",
             method="POST",
-            json_body=SandboxPresignFileParams(
-                path=path,
-                expires_in_seconds=expires_in_seconds,
-                one_time=one_time,
-            ).model_dump(exclude_none=True, by_alias=True),
+            json_body=self._with_run_as_body(
+                SandboxPresignFileParams(
+                    path=path,
+                    expires_in_seconds=expires_in_seconds,
+                    one_time=one_time,
+                ).model_dump(exclude_none=True, by_alias=True)
+            ),
             headers={"content-type": "application/json"},
         )
         return SandboxPresignedUrl(**payload)
@@ -665,11 +690,13 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/presign-download",
             method="POST",
-            json_body=SandboxPresignFileParams(
-                path=path,
-                expires_in_seconds=expires_in_seconds,
-                one_time=one_time,
-            ).model_dump(exclude_none=True, by_alias=True),
+            json_body=self._with_run_as_body(
+                SandboxPresignFileParams(
+                    path=path,
+                    expires_in_seconds=expires_in_seconds,
+                    one_time=one_time,
+                ).model_dump(exclude_none=True, by_alias=True)
+            ),
             headers={"content-type": "application/json"},
         )
         return SandboxPresignedUrl(**payload)
@@ -685,12 +712,14 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/read",
             method="POST",
-            json_body={
-                "path": path,
-                "offset": offset,
-                "length": length,
-                "encoding": encoding,
-            },
+            json_body=self._with_run_as_body(
+                {
+                    "path": path,
+                    "offset": offset,
+                    "length": length,
+                    "encoding": encoding,
+                }
+            ),
             headers={"content-type": "application/json"},
         )
         return SandboxFileReadResult(**payload)
@@ -707,13 +736,31 @@ class SandboxFilesApi:
         payload = await self._transport.request_json(
             "/sandbox/files/write",
             method="POST",
-            json_body={
-                "path": path,
-                "data": data,
-                "append": append,
-                "mode": mode,
-                "encoding": encoding,
-            },
+            json_body=self._with_run_as_body(
+                {
+                    "path": path,
+                    "data": data,
+                    "append": append,
+                    "mode": mode,
+                    "encoding": encoding,
+                }
+            ),
             headers={"content-type": "application/json"},
         )
         return _normalize_write_info(payload["files"][0])
+
+    def _with_run_as_params(
+        self, params: Dict[str, Union[str, int, bool, None]]
+    ) -> Dict[str, Union[str, int, bool, None]]:
+        if not self._default_run_as:
+            return params
+        enriched = dict(params)
+        enriched["runAs"] = self._default_run_as
+        return enriched
+
+    def _with_run_as_body(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        if not self._default_run_as:
+            return body
+        enriched = dict(body)
+        enriched["runAs"] = self._default_run_as
+        return enriched

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_processes.py

@@ -10,6 +10,7 @@ from .....models.sandbox import (
     SandboxProcessStdinParams,
     SandboxProcessSummary,
 )
+from ...sandboxes.shared import _normalize_exec_params
 from .sandbox_transport import RuntimeTransport
 
 DEFAULT_PROCESS_KILL_WAIT_SECONDS = 5.0
@@ -147,24 +148,54 @@ class SandboxProcessesApi:
     def __init__(self, transport: RuntimeTransport):
         self._transport = transport
 
-    async def exec(self, input: SandboxExecParams) -> SandboxProcessResult:
-        if not isinstance(input, SandboxExecParams):
-            raise TypeError("input must be a SandboxExecParams instance")
+    async def exec(
+        self,
+        input: Union[str, SandboxExecParams],
+        *,
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+        timeout_sec: Optional[int] = None,
+        run_as: Optional[str] = None,
+    ) -> SandboxProcessResult:
+        params = _normalize_exec_params(
+            input,
+            cwd=cwd,
+            env=env,
+            timeout_ms=timeout_ms,
+            timeout_sec=timeout_sec,
+            run_as=run_as,
+        )
         payload = await self._transport.request_json(
             "/sandbox/exec",
             method="POST",
-            json_body=input.model_dump(exclude_none=True, by_alias=True),
+            json_body=params.model_dump(exclude_none=True, by_alias=True),
             headers={"content-type": "application/json"},
         )
         return SandboxProcessResult(**payload["result"])
 
-    async def start(self, input: SandboxExecParams) -> SandboxProcessHandle:
-        if not isinstance(input, SandboxExecParams):
-            raise TypeError("input must be a SandboxExecParams instance")
+    async def start(
+        self,
+        input: Union[str, SandboxExecParams],
+        *,
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+        timeout_sec: Optional[int] = None,
+        run_as: Optional[str] = None,
+    ) -> SandboxProcessHandle:
+        params = _normalize_exec_params(
+            input,
+            cwd=cwd,
+            env=env,
+            timeout_ms=timeout_ms,
+            timeout_sec=timeout_sec,
+            run_as=run_as,
+        )
         payload = await self._transport.request_json(
             "/sandbox/processes",
             method="POST",
-            json_body=input.model_dump(exclude_none=True, by_alias=True),
+            json_body=params.model_dump(exclude_none=True, by_alias=True),
             headers={"content-type": "application/json"},
         )
         return SandboxProcessHandle(

hyperbrowser-0.90.2/hyperbrowser/client/managers/async_manager/volume.py

@@ -0,0 +1,26 @@
+from hyperbrowser.models.volume import CreateVolumeParams, Volume, VolumeListResponse
+
+
+class VolumeManager:
+    def __init__(self, client):
+        self._client = client
+
+    async def create(self, params: CreateVolumeParams) -> Volume:
+        if not isinstance(params, CreateVolumeParams):
+            raise TypeError("params must be a CreateVolumeParams instance")
+
+        response = await self._client.transport.post(
+            self._client._build_url("/volume"),
+            data=params.model_dump(exclude_none=True, by_alias=True),
+        )
+        return Volume(**response.data)
+
+    async def list(self) -> VolumeListResponse:
+        response = await self._client.transport.get(self._client._build_url("/volume"))
+        return VolumeListResponse(**response.data)
+
+    async def get(self, volume_id: str) -> Volume:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/volume/{volume_id}")
+        )
+        return Volume(**response.data)

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/managers/sandboxes/shared.py

@@ -1,11 +1,13 @@
 import base64
 import posixpath
+import re
 from datetime import datetime, timedelta, timezone
 from typing import Dict, Optional, Union
 from urllib.parse import urlencode, urlsplit, urlunsplit
 
 from ....exceptions import HyperbrowserError
 from ....models.sandbox import (
+    SandboxExecParams,
     SandboxFileInfo,
     SandboxFileWriteEntry,
     SandboxFileWriteInfo,
@@ -18,12 +20,70 @@ from ....sandbox_common import (
 )
 
 DEFAULT_WATCH_TIMEOUT_MS = 60_000
+SHELL_SAFE_TOKEN_PATTERN = re.compile(r"^[A-Za-z0-9_@%+=:,./-]+$")
 
 
 def _copy_model(model):
     return model.model_copy(deep=True)
 
 
+def _quote_shell_token(token: str) -> str:
+    if token == "":
+        return "''"
+    if SHELL_SAFE_TOKEN_PATTERN.fullmatch(token):
+        return token
+    return "'" + token.replace("'", "'\"'\"'") + "'"
+
+
+def _normalize_legacy_process_fields(params: SandboxExecParams) -> SandboxExecParams:
+    updates = {}
+
+    if params.args:
+        updates["command"] = " ".join(
+            _quote_shell_token(token) for token in [params.command, *params.args]
+        )
+
+    if params.args is not None:
+        updates["args"] = None
+
+    if params.use_shell is not None:
+        updates["use_shell"] = None
+
+    return params.model_copy(update=updates) if updates else params
+
+
+def _normalize_exec_params(
+    input: Union[str, SandboxExecParams],
+    *,
+    cwd: Optional[str] = None,
+    env: Optional[Dict[str, str]] = None,
+    timeout_ms: Optional[int] = None,
+    timeout_sec: Optional[int] = None,
+    run_as: Optional[str] = None,
+) -> SandboxExecParams:
+    if isinstance(input, str):
+        params = SandboxExecParams(command=input)
+    elif isinstance(input, SandboxExecParams):
+        params = input
+    else:
+        raise TypeError("input must be a command string or SandboxExecParams instance")
+
+    updates = {}
+    if cwd is not None:
+        updates["cwd"] = cwd
+    if env is not None:
+        updates["env"] = env
+    if timeout_ms is not None:
+        updates["timeout_ms"] = timeout_ms
+    if timeout_sec is not None:
+        updates["timeout_sec"] = timeout_sec
+    if run_as is not None:
+        updates["run_as"] = run_as
+
+    normalized = params.model_copy(update=updates) if updates else params
+    return _normalize_legacy_process_fields(normalized)
+
+
 def _build_sandbox_exposed_url(runtime, port: int) -> str:
     parsed = urlsplit(runtime.base_url)
     hostname = parsed.hostname

{hyperbrowser-0.90.0 → hyperbrowser-0.90.2}/hyperbrowser/client/managers/sync_manager/sandbox.py

@@ -217,16 +217,24 @@ class SandboxHandle:
             )
         return _copy_model(self._runtime_session)
 
-    def exec(self, input: Union[str, SandboxExecParams]):
-        if isinstance(input, str):
-            params = SandboxExecParams(command=input)
-        else:
-            if not isinstance(input, SandboxExecParams):
-                raise TypeError(
-                    "input must be a command string or SandboxExecParams instance"
-                )
-            params = input
-        return self.processes.exec(params)
+    def exec(
+        self,
+        input: Union[str, SandboxExecParams],
+        *,
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+        timeout_sec: Optional[int] = None,
+        run_as: Optional[str] = None,
+    ):
+        return self.processes.exec(
+            input,
+            cwd=cwd,
+            env=env,
+            timeout_ms=timeout_ms,
+            timeout_sec=timeout_sec,
+            run_as=run_as,
+        )
 
     def get_process(self, process_id: str) -> SandboxProcessHandle:
         return self.processes.get(process_id)