voidrun 0.0.7__tar.gz → 0.1.0__tar.gz

{voidrun-0.0.7 → voidrun-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidrun
-Version: 0.0.7
+Version: 0.1.0
 Summary: Python SDK for VoidRun AI Sandbox
 Project-URL: Homepage, https://voidrun.io
 Project-URL: Documentation, https://docs.voidrun.io
@@ -56,7 +56,7 @@ The high-level API is aligned with the official **TypeScript SDK** (`create_sand
 ## Features
 
 - **Sandbox lifecycle**: Create, list, fetch, start/stop/pause/resume, and remove sandboxes (sync and async).
-- **Shell execution**: `exec` with optional `ExecRequest`; SSE streaming via `exec_stream`.
+- **Shell execution**: synchronous `exec` with optional `ExecRequest` (no `background` flag); SSE streaming via `exec_stream`; detached processes via `.commands.run`.
 - **Code interpreter**: `run_code` / `interpreter.run` return a structured **`CodeExecutionResult`** (stdout, stderr, success, exit_code, results, logs).
 - **Files**: Create, upload, download, list, move, copy, compress, extract, permissions, search, disk usage.
 - **File watching**: WebSocket-backed directory watches (async).
@@ -244,6 +244,8 @@ Return type: **`VoidRunResponse[ExecResponseData]`**: the API’s outer **`ExecR
 print(r.data.stdout, r.data.stderr, r.data.exit_code)
 ```
 
+**`sandbox.exec` is synchronous only** — it waits for the command. Do **not** use a `background` flag on `ExecRequest`; for a PID and long-running processes, use **`sandbox.commands.run`** ([Background commands](#background-commands)).
+
 ### Streaming (`exec_stream`)
 
 Provide callbacks for SSE events (`on_stdout`, `on_stderr`, `on_exit`, `on_error`).

{voidrun-0.0.7 → voidrun-0.1.0}/README.md

@@ -32,7 +32,7 @@ The high-level API is aligned with the official **TypeScript SDK** (`create_sand
 ## Features
 
 - **Sandbox lifecycle**: Create, list, fetch, start/stop/pause/resume, and remove sandboxes (sync and async).
-- **Shell execution**: `exec` with optional `ExecRequest`; SSE streaming via `exec_stream`.
+- **Shell execution**: synchronous `exec` with optional `ExecRequest` (no `background` flag); SSE streaming via `exec_stream`; detached processes via `.commands.run`.
 - **Code interpreter**: `run_code` / `interpreter.run` return a structured **`CodeExecutionResult`** (stdout, stderr, success, exit_code, results, logs).
 - **Files**: Create, upload, download, list, move, copy, compress, extract, permissions, search, disk usage.
 - **File watching**: WebSocket-backed directory watches (async).
@@ -220,6 +220,8 @@ Return type: **`VoidRunResponse[ExecResponseData]`**: the API’s outer **`ExecR
 print(r.data.stdout, r.data.stderr, r.data.exit_code)
 ```
 
+**`sandbox.exec` is synchronous only** — it waits for the command. Do **not** use a `background` flag on `ExecRequest`; for a PID and long-running processes, use **`sandbox.commands.run`** ([Background commands](#background-commands)).
+
 ### Streaming (`exec_stream`)
 
 Provide callbacks for SSE events (`on_stdout`, `on_stderr`, `on_exit`, `on_error`).

{voidrun-0.0.7 → voidrun-0.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "voidrun"
-version = "0.0.7"
+version = "0.1.0"
 description = "Python SDK for VoidRun AI Sandbox"
 readme = "README.md"
 requires-python = ">=3.9"

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/__init__.py

@@ -11,7 +11,7 @@ from .constants import (
     DEFAULT_SANDBOX_MEM,
 )
 from .interpreter import CodeExecutionResult, CodeInterpreter, Interpreter
-from .sandbox import Sandbox
+from .sandbox import Sandbox, SandboxPublicURL
 
 __all__ = [
     "AsyncVoidRun",
@@ -25,5 +25,6 @@ __all__ = [
     "ListSandboxesMeta",
     "ListSandboxesResult",
     "Sandbox",
+    "SandboxPublicURL",
     "VoidRun",
 ]

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/api_client/api/execution_api.py

@@ -1500,7 +1500,7 @@ class ExecutionApi:
     ) -> ExecResponse:
         """Execute command (synchronous)
 
-        Execute a command in the sandbox and wait for the result
+        Execute a command in the sandbox and wait for the result. For a non-blocking start with a PID, use `POST /sandboxes/{id}/commands/run`.
 
         :param id: (required)
         :type id: str
@@ -1574,7 +1574,7 @@ class ExecutionApi:
     ) -> ApiResponse[ExecResponse]:
         """Execute command (synchronous)
 
-        Execute a command in the sandbox and wait for the result
+        Execute a command in the sandbox and wait for the result. For a non-blocking start with a PID, use `POST /sandboxes/{id}/commands/run`.
 
         :param id: (required)
         :type id: str
@@ -1648,7 +1648,7 @@ class ExecutionApi:
     ) -> RESTResponseType:
         """Execute command (synchronous)
 
-        Execute a command in the sandbox and wait for the result
+        Execute a command in the sandbox and wait for the result. For a non-blocking start with a PID, use `POST /sandboxes/{id}/commands/run`.
 
         :param id: (required)
         :type id: str

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/api_client/models/create_sandbox_request.py

@@ -37,8 +37,7 @@ class CreateSandboxRequest(BaseModel):
     env_vars: Optional[Dict[str, StrictStr]] = Field(default=None, description="Environment variables to set on the sandbox", alias="envVars")
     auto_sleep: Optional[StrictBool] = Field(default=None, description="If true, the sandbox will be auto-paused due to inactivity", alias="autoSleep")
     region: Optional[StrictStr] = Field(default=None, description="Target region for the sandbox")
-    ref_id: Optional[StrictStr] = Field(default=None, description="External reference ID for tracking", alias="refId")
-    __properties: ClassVar[List[str]] = ["name", "image", "cpu", "mem", "orgId", "userId", "sync", "envVars", "autoSleep", "region", "refId"]
+    __properties: ClassVar[List[str]] = ["name", "image", "cpu", "mem", "orgId", "userId", "sync", "envVars", "autoSleep", "region"]
 
     @field_validator('name')
     def name_validate_regular_expression(cls, value):
@@ -108,7 +107,6 @@ class CreateSandboxRequest(BaseModel):
             "envVars": obj.get("envVars"),
             "autoSleep": obj.get("autoSleep"),
             "region": obj.get("region"),
-            "refId": obj.get("refId")
         })
         return _obj
 

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/api_client/models/exec_request.py

@@ -17,7 +17,7 @@ import pprint
 import re  # noqa: F401
 import json
 
-from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt, StrictStr
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
 from typing import Any, ClassVar, Dict, List, Optional
 from typing import Optional, Set
 from typing_extensions import Self
@@ -28,11 +28,10 @@ class ExecRequest(BaseModel):
     """ # noqa: E501
     command: StrictStr
     args: Optional[List[StrictStr]] = None
-    timeout: Optional[StrictInt] = Field(default=30, description="Timeout in seconds (ignored if background=true)")
+    timeout: Optional[StrictInt] = Field(default=30, description="Timeout in seconds")
     env: Optional[Dict[str, StrictStr]] = None
     cwd: Optional[StrictStr] = None
-    background: Optional[StrictBool] = Field(default=False, description="If true, starts process in background and returns PID immediately")
-    __properties: ClassVar[List[str]] = ["command", "args", "timeout", "env", "cwd", "background"]
+    __properties: ClassVar[List[str]] = ["command", "args", "timeout", "env", "cwd"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -89,8 +88,7 @@ class ExecRequest(BaseModel):
             "args": obj.get("args"),
             "timeout": obj.get("timeout") if obj.get("timeout") is not None else 30,
             "env": obj.get("env"),
-            "cwd": obj.get("cwd"),
-            "background": obj.get("background") if obj.get("background") is not None else False
+            "cwd": obj.get("cwd")
         })
         return _obj
 

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/api_client/models/sandbox.py

@@ -33,30 +33,24 @@ class Sandbox(BaseModel):
     cpu: Optional[StrictInt] = Field(default=None, description="Number of vCPUs allocated")
     mem: Optional[StrictInt] = Field(default=None, description="Memory in MiB")
     disk_mb: Optional[StrictInt] = Field(default=None, description="Disk size in MiB", alias="diskMB")
-    status: Optional[StrictStr] = None
+    status: Optional[StrictStr] = Field(default=None, description="Lifecycle state. Terminal states `killed` and `deleted` may still appear in list responses for historical or cleanup rows.")
     created_at: Optional[datetime] = Field(default=None, alias="createdAt")
     created_by: Optional[StrictStr] = Field(default=None, description="User ID who created the sandbox", alias="createdBy")
     org_id: Optional[StrictStr] = Field(default=None, description="Organization ID the sandbox belongs to", alias="orgId")
     env_vars: Optional[Dict[str, StrictStr]] = Field(default=None, description="Environment variables set on the sandbox (optional, only present if configured)", alias="envVars")
     auto_sleep: Optional[StrictBool] = Field(default=None, description="Indicates if auto-sleep is enabled", alias="autoSleep")
     region: Optional[StrictStr] = Field(default=None, description="Region where the sandbox is hosted")
-    ref_id: Optional[StrictStr] = Field(default=None, description="External reference ID", alias="refId")
-    __properties: ClassVar[List[str]] = ["id", "name", "image", "cpu", "mem", "diskMB", "status", "createdAt", "createdBy", "orgId", "envVars", "autoSleep", "region", "refId"]
+    node_id: Optional[StrictStr] = Field(default=None, description="Voidrun host that created this sandbox", alias="nodeId")
+    __properties: ClassVar[List[str]] = ["id", "name", "image", "cpu", "mem", "diskMB", "status", "createdAt", "createdBy", "orgId", "envVars", "autoSleep", "region", "nodeId"]
 
     @field_validator('status')
     def status_validate_enum(cls, value):
-        """Validates the enum; must match voidrun/openapi.yml Sandbox.status."""
+        """Validates the enum"""
         if value is None:
             return value
 
-        allowed = frozenset(
-            ('running', 'stopped', 'paused', 'error', 'killed', 'deleted'),
-        )
-        if value not in allowed:
-            raise ValueError(
-                "must be one of enum values "
-                "('running', 'stopped', 'paused', 'error', 'killed', 'deleted')",
-            )
+        if value not in set(['running', 'stopped', 'paused', 'error', 'killed', 'deleted']):
+            raise ValueError("must be one of enum values ('running', 'stopped', 'paused', 'error', 'killed', 'deleted')")
         return value
 
     model_config = ConfigDict(
@@ -123,7 +117,7 @@ class Sandbox(BaseModel):
             "envVars": obj.get("envVars"),
             "autoSleep": obj.get("autoSleep"),
             "region": obj.get("region"),
-            "refId": obj.get("refId")
+            "nodeId": obj.get("nodeId")
         })
         return _obj
 

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/client.py

@@ -55,7 +55,6 @@ def _build_create_sandbox_request(
     env_vars: Optional[Dict[str, str]],
     auto_sleep: Optional[bool],
     region: Optional[str],
-    ref_id: Optional[str],
 ) -> CreateSandboxRequest:
     default_name = f"sdbx-{int(time.time() * 1000)}"
     org_clean = (org_id or "").strip() or None
@@ -70,7 +69,6 @@ def _build_create_sandbox_request(
         env_vars=env_vars,
         auto_sleep=auto_sleep,
         region=region,
-        ref_id=ref_id,
     )
 
 
@@ -118,8 +116,6 @@ class VoidRun:
         auto_sleep: Optional[bool] = None,
         autoSleep: Optional[bool] = None,
         region: Optional[str] = None,
-        ref_id: Optional[str] = None,
-        refId: Optional[str] = None,
         _owner: Optional[Any] = None,
     ) -> Sandbox:
         """_owner: internal — AsyncVoidRun passes itself so Sandbox uses the async client."""
@@ -133,7 +129,6 @@ class VoidRun:
         oid = (oid or "").strip() or None
         ev = env_vars if env_vars is not None else envVars
         asl = auto_sleep if auto_sleep is not None else autoSleep
-        rid = ref_id if ref_id is not None else refId
         uid = user_id if user_id is not None else userId
 
         req = _build_create_sandbox_request(
@@ -147,7 +142,6 @@ class VoidRun:
             env_vars=ev,
             auto_sleep=asl,
             region=region,
-            ref_id=rid,
         )
         response = self._sandboxes_api.create_sandbox_with_http_info(
             create_sandbox_request=req,
@@ -237,7 +231,6 @@ class SandboxesFacade:
             env_vars=kwargs.get("env_vars") or kwargs.get("envVars"),
             auto_sleep=kwargs.get("auto_sleep") or kwargs.get("autoSleep"),
             region=kwargs.get("region"),
-            ref_id=kwargs.get("ref_id") or kwargs.get("refId"),
         )
         response = self._api.create_sandbox_with_http_info(
             create_sandbox_request=req,
@@ -372,7 +365,6 @@ class AsyncSandboxesFacade:
             env_vars=kwargs.get("env_vars") or kwargs.get("envVars"),
             auto_sleep=kwargs.get("auto_sleep") or kwargs.get("autoSleep"),
             region=kwargs.get("region"),
-            ref_id=kwargs.get("ref_id") or kwargs.get("refId"),
         )
         response = await self._client._run_async(
             self._api.create_sandbox_with_http_info,

{voidrun-0.0.7 → voidrun-0.1.0}/voidrun/sandbox.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Optional, Union
+from dataclasses import dataclass
+from typing import Any, List, Optional, Union
 
 import httpx
 
@@ -16,6 +17,14 @@ from .pty import PTY
 from .response import VoidRunResponse
 
 
+@dataclass
+class SandboxPublicURL:
+    """One published sandbox port and its public URL."""
+
+    port: int
+    url: str
+
+
 class Sandbox:
     def __init__(self, client: Any, model: SandboxModel):
         self._client = client
@@ -36,7 +45,7 @@ class Sandbox:
         self.created_at = model.created_at
         self.created_by = model.created_by
         self.region = model.region
-        self.ref_id = model.ref_id
+        self.node_id = model.node_id
         self.auto_sleep = model.auto_sleep
         self.image = model.image
         self.disk_mb = model.disk_mb
@@ -170,6 +179,9 @@ class Sandbox:
     ) -> VoidRunResponse[ExecResponseData]:
         """Exec: pass a string command or an `ExecRequest` (ts-sdk style).
 
+        Synchronous only (waits for the command). There is no ``background`` field on ``ExecRequest``;
+        use ``sandbox.commands.run`` for detached processes and PIDs.
+
         Returns ``VoidRunResponse`` whose ``.data`` is ``ExecResponseData`` (stdout/stderr/exit_code),
         not the outer ``ExecResponse`` envelope, so use ``result.data.stdout`` not ``result.data.data.stdout``.
         """
@@ -267,3 +279,67 @@ class Sandbox:
             timeout=timeout,
             **kwargs,
         )
+
+    def _public_urls_request(self) -> tuple[str, dict]:
+        """URL + auth headers for the public-urls endpoint (shared by sync/async)."""
+        cfg = self._exec_api.api_client.configuration
+        url = f"{cfg.host.rstrip('/')}/sandboxes/{self.id}/public-urls"
+        headers = {"Accept": "application/json"}
+        api_key = cfg.get_api_key_with_prefix("ApiKeyAuth")
+        if api_key:
+            headers["X-API-Key"] = api_key
+        return url, headers
+
+    def get_public_urls(self, timeout: float = 15.0) -> List[SandboxPublicURL]:
+        """Public URLs for every port this sandbox publishes. Raises on HTTP >= 400."""
+        url, headers = self._public_urls_request()
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.get(url, headers=headers)
+            resp.raise_for_status()
+            return _parse_public_urls(resp.json())
+
+    async def get_public_urls_async(
+        self, timeout: float = 15.0
+    ) -> List[SandboxPublicURL]:
+        url, headers = self._public_urls_request()
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(url, headers=headers)
+            resp.raise_for_status()
+            return _parse_public_urls(resp.json())
+
+    def get_public_url(self, port: int, timeout: float = 15.0) -> Optional[SandboxPublicURL]:
+        """Public URL for one published port, or ``None`` if not published."""
+        for entry in self.get_public_urls(timeout=timeout):
+            if entry.port == port:
+                return entry
+        return None
+
+    async def get_public_url_async(
+        self, port: int, timeout: float = 15.0
+    ) -> Optional[SandboxPublicURL]:
+        for entry in await self.get_public_urls_async(timeout=timeout):
+            if entry.port == port:
+                return entry
+        return None
+
+
+def _parse_public_urls(body: Any) -> List[SandboxPublicURL]:
+    data = body.get("data") if isinstance(body, dict) else None
+    if not isinstance(data, list):
+        return []
+    out: List[SandboxPublicURL] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        raw_port = item.get("port")
+        try:
+            port = int(raw_port) if isinstance(raw_port, (int, str)) else -1
+        except (TypeError, ValueError):
+            continue
+        if not (1 <= port <= 65535):
+            continue
+        url = item.get("url")
+        if not isinstance(url, str) or not url:
+            continue
+        out.append(SandboxPublicURL(port=port, url=url))
+    return out