abox-sdk 0.1.0__tar.gz

abox_sdk-0.1.0/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) 2025 FOUNDRYLABS, INC.
+Copyright (c) 2026 RetailDriver LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

abox_sdk-0.1.0/NOTICE

@@ -0,0 +1 @@
+This package is part of AgentBox SDK. It contains software derived from the E2B SDK by FOUNDRYLABS, INC. at commit 5a56c87e9db0e221b138662805af7743e75f1082. See https://github.com/abox-dev/sdk/blob/main/UPSTREAM.md.

abox_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: abox-sdk
+Version: 0.1.0
+Summary: AgentBox SDK for secure cloud sandboxes
+Author: RetailDriver LLC
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: wcmatch>=10.1,<12
+Requires-Dist: protobuf-py>=0.1.1,<0.2
+Requires-Dist: httpx>=0.27.0,<1.0.0
+Requires-Dist: h2>=4.4.1,<5
+Requires-Dist: attrs>=23.2.0
+Requires-Dist: packaging>=24.1
+Requires-Dist: typing-extensions>=4.10.0
+Requires-Dist: dockerfile-parse>=2.0.1,<3
+Requires-Dist: rich>=14.0.0
+Requires-Dist: connectrpc>=0.11.1,<0.12
+Requires-Dist: pyqwest>=0.10.0,<0.11
+Requires-Python: >=3.10
+Project-URL: Homepage, https://docs.agentbox.ru/en/sdk/
+Project-URL: Documentation, https://docs.agentbox.ru/en/sdk/api-reference/python/
+Project-URL: Repository, https://github.com/abox-dev/sdk/tree/main/packages/python-sdk
+Project-URL: Bug Tracker, https://github.com/abox-dev/sdk/issues
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/abox-dev/sdk/main/readme-assets/agentbox-logo-email.png" alt="AgentBox" width="240"></p>
+
+# `abox-sdk`
+
+The official Python SDK for AgentBox sandboxes and templates. The distribution is named `abox-sdk`; the Python package is `agentbox`.
+
+```bash
+pip install abox-sdk
+```
+
+Create an API key using the [API key guide](https://docs.agentbox.ru/en/quickstart/api-key/) and set `AGENTBOX_API_KEY`.
+
+```python
+from agentbox import Sandbox
+
+with Sandbox.create() as sandbox:
+    result = sandbox.commands.run('echo "Hello from AgentBox"')
+    print(result.stdout)
+```
+
+Async and explicitly configured clients are supported:
+
+```python
+from agentbox import AgentBox
+
+client = AgentBox(api_key="ab_...")
+sandbox = await client.AsyncSandbox.create()
+```
+
+Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/python/).

abox_sdk-0.1.0/README.md

@@ -0,0 +1,30 @@
+<p align="center"><img src="https://raw.githubusercontent.com/abox-dev/sdk/main/readme-assets/agentbox-logo-email.png" alt="AgentBox" width="240"></p>
+
+# `abox-sdk`
+
+The official Python SDK for AgentBox sandboxes and templates. The distribution is named `abox-sdk`; the Python package is `agentbox`.
+
+```bash
+pip install abox-sdk
+```
+
+Create an API key using the [API key guide](https://docs.agentbox.ru/en/quickstart/api-key/) and set `AGENTBOX_API_KEY`.
+
+```python
+from agentbox import Sandbox
+
+with Sandbox.create() as sandbox:
+    result = sandbox.commands.run('echo "Hello from AgentBox"')
+    print(result.stdout)
+```
+
+Async and explicitly configured clients are supported:
+
+```python
+from agentbox import AgentBox
+
+client = AgentBox(api_key="ab_...")
+sandbox = await client.AsyncSandbox.create()
+```
+
+Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/python/).

abox_sdk-0.1.0/agentbox/__init__.py

@@ -0,0 +1,96 @@
+"""AgentBox SDK for secure cloud sandboxes."""
+
+from .api import ApiClient, client
+from .client import AgentBox, AgentBoxClientParams
+from .connection_config import ApiParams, ConnectionConfig, ProxyTypes, Username
+from .exceptions import (
+    AuthenticationException,
+    BuildException,
+    FileNotFoundException,
+    FileUploadException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    RateLimitException,
+    SandboxException,
+    SandboxNotFoundException,
+    TemplateException,
+    TimeoutException,
+)
+from .sandbox.commands.command_handle import (
+    CommandExitException,
+    CommandResult,
+    PtyOutput,
+    PtySize,
+    Stderr,
+    Stdout,
+)
+from .sandbox.commands.main import ProcessInfo
+from .sandbox.filesystem.filesystem import EntryInfo, FileType, WriteInfo
+from .sandbox.filesystem.watch_handle import FilesystemEvent, FilesystemEventType
+from .sandbox.network import ALL_TRAFFIC
+from .sandbox.sandbox_api import (
+    GitHubMcpServer,
+    GitHubMcpServerConfig,
+    McpServer,
+    SandboxIamOpts,
+    SandboxIamToken,
+    SandboxIamTokenType,
+    SandboxInfo,
+    SandboxInfoLifecycle,
+    SandboxLifecycle,
+    SandboxMetrics,
+    SandboxNetworkInfo,
+    SandboxNetworkOpts,
+    SandboxNetworkRule,
+    SandboxNetworkRuleInfo,
+    SandboxNetworkRules,
+    SandboxNetworkSelector,
+    SandboxNetworkSelectorContext,
+    SandboxNetworkTransform,
+    SandboxNetworkTransformContext,
+    SandboxNetworkTransformResolver,
+    SandboxNetworkUpdate,
+    SandboxOnTimeout,
+    SandboxQuery,
+    SandboxState,
+    SnapshotInfo,
+)
+from .sandbox.signature import get_signature
+from .sandbox_async.commands.command_handle import AsyncCommandHandle
+from .sandbox_async.filesystem.watch_handle import AsyncWatchHandle
+from .sandbox_async.main import AsyncSandbox
+from .sandbox_async.paginator import AsyncSandboxPaginator, AsyncSnapshotPaginator
+from .sandbox_async.utils import OutputHandler
+from .sandbox_sync.commands.command_handle import CommandHandle
+from .sandbox_sync.filesystem.watch_handle import WatchHandle
+from .sandbox_sync.main import Sandbox
+from .sandbox_sync.paginator import SandboxPaginator, SnapshotPaginator
+from .template.logger import (
+    LogEntry,
+    LogEntryEnd,
+    LogEntryLevel,
+    LogEntryStart,
+    default_build_logger,
+)
+from .template.main import TemplateBase, TemplateClass
+from .template.readycmd import (
+    ReadyCmd,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .template.types import (
+    BuildInfo,
+    BuildStatusReason,
+    CopyItem,
+    TemplateBuildStatus,
+    TemplateBuildStatusResponse,
+    TemplateTag,
+    TemplateTagInfo,
+)
+from .template_async.main import AsyncTemplate
+from .template_sync.main import Template
+
+__all__ = [name for name in globals() if not name.startswith("_")]

abox_sdk-0.1.0/agentbox/api/__init__.py

@@ -0,0 +1,274 @@
+import json
+import logging
+import os
+from dataclasses import dataclass
+from types import TracebackType
+from typing import NamedTuple, Optional, Protocol, Tuple, Union
+from urllib.parse import quote
+
+import httpx
+from httpx import AsyncBaseTransport, BaseTransport, Timeout
+from pyqwest import Proxy
+
+from agentbox.api.client.client import AuthenticatedClient
+from agentbox.api.client.types import Response
+from agentbox.api.metadata import default_headers
+from agentbox.connection_config import ConnectionConfig, ProxyTypes
+from agentbox.exceptions import (
+    AuthenticationException,
+    InvalidArgumentException,
+    RateLimitException,
+    SandboxException,
+)
+
+
+def encode_path_param(value: str) -> str:
+    """
+    Percent-encode a template ID, name, or alias for use as one URL path segment.
+
+    Endpoints that take a template ID also accept a name, which may be
+    namespaced (``namespace/name``) and carry a ``:tag``. Escaping those
+    separators keeps the value inside a single segment instead of splitting the
+    route, matching the JS SDK's ``encodeURIComponent``.
+    """
+    return quote(value, safe="")
+
+
+def make_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Build synchronous httpx ``event_hooks`` that log requests and responses
+    to the given ``logging.Logger``. Requests log at ``INFO``, successful
+    responses at ``INFO`` and responses with status >= 400 at ``ERROR``.
+
+    Returns no hooks when ``log`` is ``None`` so that nothing is logged unless a
+    logger was explicitly supplied."""
+    if log is None:
+        return {}
+
+    def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+def make_async_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Asynchronous counterpart of :func:`make_logging_event_hooks`."""
+    if log is None:
+        return {}
+
+    async def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    async def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+connection_retries = int(os.getenv("AGENTBOX_CONNECTION_RETRIES") or "3")
+
+# Pool tuning for the pyqwest transports, shared by the REST API, envd RPC,
+# and envd HTTP API stacks. `pool_max_idle_per_host` is per host rather than
+# the global idle cap the httpx transports took, which suits both: API traffic
+# goes to a single host and each sandbox is its own host. `AGENTBOX_MAX_CONNECTIONS`
+# has no counterpart left — reqwest does not cap concurrent connections — so it
+# is no longer read.
+pool_idle_timeout = float(os.getenv("AGENTBOX_KEEPALIVE_EXPIRY") or "300")
+pool_max_idle_per_host = int(os.getenv("AGENTBOX_MAX_KEEPALIVE_CONNECTIONS") or "20")
+
+
+class ProxyConfig(NamedTuple):
+    """The ``proxy`` connection option in the shape pyqwest transports take.
+
+    A tuple so it can key the transport caches directly: it is hashable and
+    compares by value, where a ``pyqwest.Proxy`` compares by identity and
+    would hand every call its own connection pool."""
+
+    url: str
+    auth: Optional[Tuple[str, str]] = None
+    headers: Tuple[Tuple[str, str], ...] = ()
+
+    def to_pyqwest(self) -> Proxy:
+        """The ``pyqwest.Proxy`` to hand a transport."""
+        return Proxy(self.url, auth=self.auth, headers=self.headers or None)
+
+
+def proxy_to_config(proxy: Optional[ProxyTypes]) -> Optional[ProxyConfig]:
+    """Convert the ``proxy`` connection option — a URL string, an
+    ``httpx.URL``, or an ``httpx.Proxy`` — to the proxy configuration pyqwest
+    transports take: a proxy URL (scheme http, https, socks5, or socks5h,
+    credentials allowed in the userinfo), basic-auth credentials, and headers
+    to send to the proxy. An ``httpx.Proxy`` ``ssl_context`` has no pyqwest
+    counterpart and is rejected rather than silently dropped."""
+    if proxy is None:
+        return None
+    if isinstance(proxy, str):
+        return ProxyConfig(proxy)
+    if isinstance(proxy, httpx.URL):
+        return ProxyConfig(str(proxy))
+    if isinstance(proxy, httpx.Proxy):
+        if proxy.ssl_context is not None:
+            raise InvalidArgumentException("httpx.Proxy ssl_context is not supported")
+        # httpx.Proxy splits userinfo out of the URL into `.auth`; pyqwest
+        # takes the credentials the same way, so they pass straight through.
+        return ProxyConfig(
+            str(proxy.url),
+            auth=proxy.auth,
+            headers=tuple(proxy.headers.items()),
+        )
+    raise InvalidArgumentException(
+        "Only URL-string, httpx.URL, and httpx.Proxy proxies are supported, "
+        'e.g. proxy="http://user:pass@localhost:8030"'
+    )
+
+
+@dataclass
+class SandboxCreateResponse:
+    sandbox_id: str
+    sandbox_domain: Optional[str]
+    envd_version: str
+    envd_access_token: Optional[str]
+    traffic_access_token: Optional[str]
+
+
+def api_exception_from_code(
+    status_code: int,
+    message: Optional[str] = None,
+    default_exception_class: type[Exception] = SandboxException,
+    stack_trace: Optional[TracebackType] = None,
+) -> Exception:
+    """Map an API error code and message to the matching exception class — the
+    same mapping :func:`handle_api_exception` applies to HTTP responses, usable
+    for error objects embedded in response bodies (e.g. per-fork results)."""
+    if status_code == 401:
+        text = f"{status_code}: Unauthorized, please check your credentials."
+        if message:
+            text += f" - {message}"
+        return AuthenticationException(text)
+
+    if status_code == 429:
+        text = f"{status_code}: Rate limit exceeded, please try again later."
+        if message:
+            text += f" - {message}"
+        return RateLimitException(text)
+
+    return default_exception_class(f"{status_code}: {message}").with_traceback(
+        stack_trace
+    )
+
+
+def handle_api_exception(
+    e: "SupportsApiErrorResponse",
+    default_exception_class: type[Exception] = SandboxException,
+    stack_trace: Optional[TracebackType] = None,
+):
+    try:
+        body = json.loads(e.content) if e.content else {}
+    except json.JSONDecodeError:
+        body = {}
+
+    message = body["message"] if "message" in body else None
+    if message is None and e.status_code not in (401, 429):
+        return default_exception_class(f"{e.status_code}: {e.content}").with_traceback(
+            stack_trace
+        )
+
+    return api_exception_from_code(
+        e.status_code, message, default_exception_class, stack_trace
+    )
+
+
+class SupportsApiErrorResponse(Protocol):
+    @property
+    def status_code(self) -> int: ...
+
+    @property
+    def content(self) -> Union[str, bytes]: ...
+
+
+class ApiClient(AuthenticatedClient):
+    """
+    The client for interacting with the AgentBox API.
+
+    A single lazily-created httpx client (see the generated
+    ``AuthenticatedClient``) serves all threads and event loops: the pyqwest
+    transports it delegates to are thread-safe and loop-independent, and
+    ``httpx.Client`` is documented thread-safe.
+    """
+
+    def __init__(
+        self,
+        config: ConnectionConfig,
+        transport: Optional[Union[BaseTransport, AsyncBaseTransport]] = None,
+        *args,
+        **kwargs,
+    ):
+        self._proxy = config.proxy
+
+        if config.api_key is None:
+            raise AuthenticationException(
+                "AgentBox API key is required. See https://docs.agentbox.ru/en/quickstart/api-key/ for setup instructions. "
+                "You can either set the environment variable `AGENTBOX_API_KEY` "
+                'or pass it directly to the method like api_key="ab_...".',
+            )
+
+        token = config.api_key
+        auth_header_name = "X-API-KEY"
+        prefix = ""
+
+        self._logger = config.logger
+
+        headers = {
+            **default_headers,
+            **(config.headers or {}),
+        }
+
+        # Prevent passing these parameters twice
+        more_headers: Optional[dict] = kwargs.pop("headers", None)
+        if more_headers:
+            headers.update(more_headers)
+        kwargs.pop("token", None)
+        kwargs.pop("auth_header_name", None)
+        kwargs.pop("prefix", None)
+
+        httpx_args = {
+            "event_hooks": self._logging_event_hooks(),
+        }
+        if transport is not None:
+            # The proxy lives in the transport; passing `proxy` here too
+            # would mount a fresh, never-closed proxy transport per client.
+            httpx_args["transport"] = transport
+        else:
+            httpx_args["proxy"] = config.proxy
+
+        # config.request_timeout is None when the timeout is explicitly
+        # disabled (request_timeout=0), which httpx.Timeout(None) preserves.
+        kwargs.setdefault("timeout", Timeout(config.request_timeout))
+
+        super().__init__(
+            base_url=config.api_url,
+            httpx_args=httpx_args,
+            headers=headers,
+            token=token or "",
+            auth_header_name=auth_header_name,
+            prefix=prefix,
+            *args,
+            **kwargs,
+        )
+
+    def _logging_event_hooks(self) -> dict:
+        return make_logging_event_hooks(self._logger)
+
+
+# We need to override the logging hooks for the async usage
+class AsyncApiClient(ApiClient):
+    def _logging_event_hooks(self) -> dict:
+        return make_async_logging_event_hooks(self._logger)

abox_sdk-0.1.0/agentbox/api/client/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing AgentBox API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

abox_sdk-0.1.0/agentbox/api/client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

abox_sdk-0.1.0/agentbox/api/client/api/sandboxes/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

abox_sdk-0.1.0/agentbox/api/client/api/sandboxes/delete_sandboxes_sandbox_id.py

@@ -0,0 +1,169 @@
+from http import HTTPStatus
+from typing import Any, Optional, Union, cast
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error import Error
+from ...types import Response
+
+
+def _get_kwargs(
+    sandbox_id: str,
+) -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
+        "method": "delete",
+        "url": f"/sandboxes/{sandbox_id}",
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Optional[Union[Any, Error]]:
+    if response.status_code == 204:
+        response_204 = cast(Any, None)
+        return response_204
+    if response.status_code == 401:
+        response_401 = Error.from_dict(response.json())
+
+        return response_401
+    if response.status_code == 404:
+        response_404 = Error.from_dict(response.json())
+
+        return response_404
+    if response.status_code == 500:
+        response_500 = Error.from_dict(response.json())
+
+        return response_500
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Response[Union[Any, Error]]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    sandbox_id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+) -> Response[Union[Any, Error]]:
+    """Kill sandbox
+
+     Kill a sandbox
+
+    Args:
+        sandbox_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Union[Any, Error]]
+    """
+
+    kwargs = _get_kwargs(
+        sandbox_id=sandbox_id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    sandbox_id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+) -> Optional[Union[Any, Error]]:
+    """Kill sandbox
+
+     Kill a sandbox
+
+    Args:
+        sandbox_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Union[Any, Error]
+    """
+
+    return sync_detailed(
+        sandbox_id=sandbox_id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    sandbox_id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+) -> Response[Union[Any, Error]]:
+    """Kill sandbox
+
+     Kill a sandbox
+
+    Args:
+        sandbox_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Union[Any, Error]]
+    """
+
+    kwargs = _get_kwargs(
+        sandbox_id=sandbox_id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    sandbox_id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+) -> Optional[Union[Any, Error]]:
+    """Kill sandbox
+
+     Kill a sandbox
+
+    Args:
+        sandbox_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Union[Any, Error]
+    """
+
+    return (
+        await asyncio_detailed(
+            sandbox_id=sandbox_id,
+            client=client,
+        )
+    ).parsed