moru 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

moru/sandbox_async/commands/command.py

@@ -15,7 +15,11 @@ from moru.envd.versions import ENVD_COMMANDS_STDIN
 from moru.exceptions import SandboxException
 from moru.sandbox.commands.main import ProcessInfo
 from moru.sandbox.commands.command_handle import CommandResult
-from moru.sandbox_async.commands.command_handle import AsyncCommandHandle, Stderr, Stdout
+from moru.sandbox_async.commands.command_handle import (
+    AsyncCommandHandle,
+    Stderr,
+    Stdout,
+)
 from moru.sandbox_async.utils import OutputHandler
 
 

moru/sandbox_async/filesystem/filesystem.py

@@ -16,7 +16,11 @@ from moru.envd.api import ENVD_API_FILES_ROUTE, ahandle_envd_api_exception
 from moru.envd.filesystem import filesystem_connect, filesystem_pb2
 from moru.envd.rpc import authentication_header, handle_rpc_exception
 from moru.envd.versions import ENVD_VERSION_RECURSIVE_WATCH, ENVD_DEFAULT_USER
-from moru.exceptions import SandboxException, TemplateException, InvalidArgumentException
+from moru.exceptions import (
+    SandboxException,
+    TemplateException,
+    InvalidArgumentException,
+)
 from moru.sandbox.filesystem.filesystem import (
     WriteInfo,
     EntryInfo,

moru/sandbox_async/main.py

@@ -16,6 +16,7 @@ from moru.exceptions import SandboxException, format_request_timeout_error
 from moru.sandbox.main import SandboxOpts
 from moru.sandbox.sandbox_api import McpServer, SandboxMetrics, SandboxNetworkOpts
 from moru.sandbox.utils import class_method_variant
+from moru.volume.volume_api import validate_mount_path
 from moru.sandbox_async.commands.command import Commands
 from moru.sandbox_async.commands.pty import Pty
 from moru.sandbox_async.filesystem.filesystem import Filesystem
@@ -153,6 +154,8 @@ class AsyncSandbox(SandboxApi):
         allow_internet_access: bool = True,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -168,11 +171,23 @@ class AsyncSandbox(SandboxApi):
         :param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`.
         :param mcp: MCP server to enable in the sandbox
         :param network: Sandbox network configuration
+        :param volume_id: Volume ID to attach (e.g., vol_abc123). Requires volume_mount_path.
+        :param volume_mount_path: Mount path inside sandbox. Required if volume_id is provided.
+            Must start with /workspace/, /data/, /mnt/, or /volumes/.
+            Note: Mounting overlays any existing files/directories at the mount path.
 
         :return: A Sandbox instance for the new sandbox
 
         Use this method instead of using the constructor to create a new sandbox.
         """
+        # Validate volume parameters
+        if volume_id and not volume_mount_path:
+            raise ValueError("volume_mount_path is required when volume_id is provided")
+        if volume_mount_path and not volume_id:
+            raise ValueError("volume_id is required when volume_mount_path is provided")
+        if volume_mount_path:
+            validate_mount_path(volume_mount_path)
+
         if not template and mcp is not None:
             template = cls.default_mcp_template
         elif not template:
@@ -188,6 +203,8 @@ class AsyncSandbox(SandboxApi):
             allow_internet_access=allow_internet_access,
             mcp=mcp,
             network=network,
+            volume_id=volume_id,
+            volume_mount_path=volume_mount_path,
             **opts,
         )
 
@@ -680,6 +697,8 @@ class AsyncSandbox(SandboxApi):
         secure: bool,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         extra_sandbox_headers = {}
@@ -702,6 +721,8 @@ class AsyncSandbox(SandboxApi):
                 allow_internet_access=allow_internet_access,
                 mcp=mcp,
                 network=network,
+                volume_id=volume_id,
+                volume_mount_path=volume_mount_path,
                 **opts,
             )
 

moru/sandbox_async/sandbox_api.py

@@ -159,23 +159,29 @@ class SandboxApi(SandboxBase):
         secure: bool,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SandboxCreateResponse:
         config = ConnectionConfig(**opts)
 
         api_client = get_api_client(config)
+        new_sandbox = NewSandbox(
+            template_id=template,
+            auto_pause=auto_pause,
+            metadata=metadata or {},
+            timeout=timeout,
+            env_vars=env_vars or {},
+            mcp=mcp or UNSET,
+            secure=secure,
+            allow_internet_access=allow_internet_access,
+            network=SandboxNetworkConfig(**network) if network else UNSET,
+            volume_id=volume_id or UNSET,
+            volume_mount_path=volume_mount_path or UNSET,
+        )
+
         res = await post_sandboxes.asyncio_detailed(
-            body=NewSandbox(
-                template_id=template,
-                auto_pause=auto_pause,
-                metadata=metadata or {},
-                timeout=timeout,
-                env_vars=env_vars or {},
-                mcp=mcp or UNSET,
-                secure=secure,
-                allow_internet_access=allow_internet_access,
-                network=SandboxNetworkConfig(**network) if network else UNSET,
-            ),
+            body=new_sandbox,
             client=api_client,
         )
 

moru/sandbox_sync/filesystem/filesystem.py

@@ -9,7 +9,11 @@ import httpx
 from packaging.version import Version
 
 from moru.envd.versions import ENVD_VERSION_RECURSIVE_WATCH, ENVD_DEFAULT_USER
-from moru.exceptions import SandboxException, TemplateException, InvalidArgumentException
+from moru.exceptions import (
+    SandboxException,
+    TemplateException,
+    InvalidArgumentException,
+)
 from moru.connection_config import (
     ConnectionConfig,
     Username,

moru/sandbox_sync/main.py

@@ -16,6 +16,7 @@ from moru.exceptions import SandboxException, format_request_timeout_error
 from moru.sandbox.main import SandboxOpts
 from moru.sandbox.sandbox_api import McpServer, SandboxMetrics, SandboxNetworkOpts
 from moru.sandbox.utils import class_method_variant
+from moru.volume.volume_api import validate_mount_path
 from moru.sandbox_sync.commands.command import Commands
 from moru.sandbox_sync.commands.pty import Pty
 from moru.sandbox_sync.filesystem.filesystem import Filesystem
@@ -151,6 +152,8 @@ class Sandbox(SandboxApi):
         allow_internet_access: bool = True,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -166,11 +169,23 @@ class Sandbox(SandboxApi):
         :param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`.
         :param mcp: MCP server to enable in the sandbox
         :param network: Sandbox network configuration
+        :param volume_id: Volume ID to attach (e.g., vol_abc123). Requires volume_mount_path.
+        :param volume_mount_path: Mount path inside sandbox. Required if volume_id is provided.
+            Must start with /workspace/, /data/, /mnt/, or /volumes/.
+            Note: Mounting overlays any existing files/directories at the mount path.
 
         :return: A Sandbox instance for the new sandbox
 
         Use this method instead of using the constructor to create a new sandbox.
         """
+        # Validate volume parameters
+        if volume_id and not volume_mount_path:
+            raise ValueError("volume_mount_path is required when volume_id is provided")
+        if volume_mount_path and not volume_id:
+            raise ValueError("volume_id is required when volume_mount_path is provided")
+        if volume_mount_path:
+            validate_mount_path(volume_mount_path)
+
         if not template and mcp is not None:
             template = cls.default_mcp_template
         elif not template:
@@ -186,6 +201,8 @@ class Sandbox(SandboxApi):
             allow_internet_access=allow_internet_access,
             mcp=mcp,
             network=network,
+            volume_id=volume_id,
+            volume_mount_path=volume_mount_path,
             **opts,
         )
 
@@ -672,6 +689,8 @@ class Sandbox(SandboxApi):
         allow_internet_access: bool,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         extra_sandbox_headers = {}
@@ -694,6 +713,8 @@ class Sandbox(SandboxApi):
                 allow_internet_access=allow_internet_access,
                 mcp=mcp,
                 network=network,
+                volume_id=volume_id,
+                volume_mount_path=volume_mount_path,
                 **opts,
             )
 

moru/sandbox_sync/sandbox_api.py

@@ -158,23 +158,29 @@ class SandboxApi(SandboxBase):
         secure: bool,
         mcp: Optional[McpServer] = None,
         network: Optional[SandboxNetworkOpts] = None,
+        volume_id: Optional[str] = None,
+        volume_mount_path: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SandboxCreateResponse:
         config = ConnectionConfig(**opts)
 
         api_client = get_api_client(config)
+        new_sandbox = NewSandbox(
+            template_id=template,
+            auto_pause=auto_pause,
+            metadata=metadata or {},
+            timeout=timeout,
+            env_vars=env_vars or {},
+            mcp=mcp or UNSET,
+            secure=secure,
+            allow_internet_access=allow_internet_access,
+            network=SandboxNetworkConfig(**network) if network else UNSET,
+            volume_id=volume_id or UNSET,
+            volume_mount_path=volume_mount_path or UNSET,
+        )
+
         res = post_sandboxes.sync_detailed(
-            body=NewSandbox(
-                template_id=template,
-                auto_pause=auto_pause,
-                metadata=metadata or {},
-                timeout=timeout,
-                env_vars=env_vars or {},
-                mcp=mcp or UNSET,
-                secure=secure,
-                allow_internet_access=allow_internet_access,
-                network=SandboxNetworkConfig(**network) if network else UNSET,
-            ),
+            body=new_sandbox,
             client=api_client,
         )
 

moru/volume/__init__.py

@@ -0,0 +1,11 @@
+"""Volume module for persistent storage."""
+
+from .types import FileInfo, FileType, VolumeInfo
+from .volume_api import VolumeApi
+
+__all__ = [
+    "FileInfo",
+    "FileType",
+    "VolumeApi",
+    "VolumeInfo",
+]

moru/volume/types.py

@@ -0,0 +1,83 @@
+"""Volume type definitions."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+
+class FileType(str, Enum):
+    """Type of file system entry."""
+
+    FILE = "file"
+    DIRECTORY = "directory"
+
+
+@dataclass
+class FileInfo:
+    """Information about a file or directory in a volume."""
+
+    name: str
+    """File or directory name."""
+
+    path: str
+    """Full path within volume."""
+
+    type: FileType
+    """Entry type (file or directory)."""
+
+    size: Optional[int] = None
+    """File size in bytes (only for files)."""
+
+    modified_at: Optional[datetime] = None
+    """Last modification time."""
+
+    @classmethod
+    def _from_api_response(cls, data: dict) -> "FileInfo":
+        """Create FileInfo from API response data."""
+        return cls(
+            name=data["name"],
+            path=data["path"],
+            type=FileType(data["type"]),
+            size=data.get("size"),
+            modified_at=(
+                datetime.fromisoformat(data["modifiedAt"].replace("Z", "+00:00"))
+                if data.get("modifiedAt")
+                else None
+            ),
+        )
+
+
+@dataclass
+class VolumeInfo:
+    """Information about a volume."""
+
+    volume_id: str
+    """Unique volume identifier."""
+
+    name: str
+    """Volume name."""
+
+    total_size_bytes: int
+    """Total size of files in volume (bytes)."""
+
+    total_file_count: int
+    """Total number of files in volume."""
+
+    created_at: datetime
+    """When the volume was created."""
+
+    updated_at: datetime
+    """When the volume was last updated."""
+
+    @classmethod
+    def _from_api_response(cls, data: dict) -> "VolumeInfo":
+        """Create VolumeInfo from API response data."""
+        return cls(
+            volume_id=data["volumeID"],
+            name=data["name"],
+            total_size_bytes=data.get("totalSizeBytes", 0),
+            total_file_count=data.get("totalFileCount", 0),
+            created_at=datetime.fromisoformat(data["createdAt"].replace("Z", "+00:00")),
+            updated_at=datetime.fromisoformat(data["updatedAt"].replace("Z", "+00:00")),
+        )

moru/volume/volume_api.py

@@ -0,0 +1,330 @@
+"""Base VolumeApi class with static methods for volume operations."""
+
+from typing import List, Optional, Tuple
+
+from typing_extensions import Unpack
+
+from moru.api import ApiClient, handle_api_exception
+from moru.api.client_sync import get_api_client
+from moru.connection_config import ApiParams, ConnectionConfig
+from moru.exceptions import NotFoundException
+
+from .types import FileInfo, VolumeInfo
+
+
+# Allowed mount path prefixes for sandbox volume attachment
+ALLOWED_MOUNT_PREFIXES = ("/workspace/", "/data/", "/mnt/", "/volumes/")
+
+
+def validate_mount_path(path: str) -> None:
+    """
+    Validate volume mount path.
+
+    :param path: Mount path to validate
+    :raises ValueError: If path is invalid
+
+    Allowed prefixes: /workspace/, /data/, /mnt/, /volumes/
+    """
+    if not path:
+        raise ValueError("Mount path cannot be empty")
+
+    if not path.startswith("/"):
+        raise ValueError("Mount path must be absolute (start with /)")
+
+    # Check allowed prefixes
+    if not any(path.startswith(prefix) for prefix in ALLOWED_MOUNT_PREFIXES):
+        raise ValueError(
+            f"Mount path must start with one of: {', '.join(ALLOWED_MOUNT_PREFIXES)}"
+        )
+
+    # Check for directory traversal
+    if ".." in path:
+        raise ValueError("Mount path cannot contain '..'")
+
+    # Check that path has a subdirectory after prefix
+    # e.g., /workspace is not valid, but /workspace/data is
+    for prefix in ALLOWED_MOUNT_PREFIXES:
+        if path.startswith(prefix):
+            remainder = path[len(prefix) :]
+            # Empty remainder means path is just the prefix without trailing content
+            # This is actually valid - /workspace/ should work
+            break
+
+
+class VolumeApi:
+    """Base class for volume API operations."""
+
+    @staticmethod
+    def _create_volume(
+        name: str,
+        **opts: Unpack[ApiParams],
+    ) -> VolumeInfo:
+        """
+        Create a new volume (idempotent).
+
+        :param name: Volume name
+        :return: Volume info
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        response = client.post(
+            f"{config.api_url}/volumes",
+            json={"name": name},
+            timeout=config.request_timeout,
+        )
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return VolumeInfo._from_api_response(response.json())
+
+    @staticmethod
+    def _get_volume(
+        volume_id_or_name: str,
+        **opts: Unpack[ApiParams],
+    ) -> VolumeInfo:
+        """
+        Get volume by ID or name.
+
+        :param volume_id_or_name: Volume ID (vol_xxx) or name
+        :return: Volume info
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        response = client.get(
+            f"{config.api_url}/volumes/{volume_id_or_name}",
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundException(f"Volume '{volume_id_or_name}' not found")
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return VolumeInfo._from_api_response(response.json())
+
+    @staticmethod
+    def _list_volumes(
+        limit: Optional[int] = None,
+        next_token: Optional[str] = None,
+        **opts: Unpack[ApiParams],
+    ) -> Tuple[List[VolumeInfo], Optional[str]]:
+        """
+        List all volumes.
+
+        :param limit: Maximum number of volumes to return
+        :param next_token: Pagination token
+        :return: Tuple of (volumes, next_token)
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if next_token is not None:
+            params["nextToken"] = next_token
+
+        response = client.get(
+            f"{config.api_url}/volumes",
+            params=params,
+            timeout=config.request_timeout,
+        )
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        volumes = [VolumeInfo._from_api_response(v) for v in response.json()]
+        result_next_token = response.headers.get("x-next-token")
+
+        return volumes, result_next_token
+
+    @staticmethod
+    def _delete_volume(
+        volume_id_or_name: str,
+        **opts: Unpack[ApiParams],
+    ) -> bool:
+        """
+        Delete a volume.
+
+        :param volume_id_or_name: Volume ID (vol_xxx) or name
+        :return: True if deleted, False if not found
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        response = client.delete(
+            f"{config.api_url}/volumes/{volume_id_or_name}",
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            return False
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return True
+
+    @staticmethod
+    def _list_files(
+        volume_id: str,
+        path: str = "/",
+        limit: Optional[int] = None,
+        next_token: Optional[str] = None,
+        **opts: Unpack[ApiParams],
+    ) -> Tuple[List[FileInfo], Optional[str]]:
+        """
+        List files in a volume.
+
+        :param volume_id: Volume ID (vol_xxx)
+        :param path: Directory path to list
+        :param limit: Maximum number of files to return
+        :param next_token: Pagination token
+        :return: Tuple of (files, next_token)
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        params = {"path": path}
+        if limit is not None:
+            params["limit"] = limit
+        if next_token is not None:
+            params["nextToken"] = next_token
+
+        response = client.get(
+            f"{config.api_url}/volumes/{volume_id}/files",
+            params=params,
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundException(f"Volume '{volume_id}' not found")
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        data = response.json()
+        files = [FileInfo._from_api_response(f) for f in data.get("files", [])]
+        result_next_token = data.get("nextToken")
+
+        return files, result_next_token
+
+    @staticmethod
+    def _upload_file(
+        volume_id: str,
+        path: str,
+        content: bytes,
+        **opts: Unpack[ApiParams],
+    ) -> int:
+        """
+        Upload file content to volume.
+
+        :param volume_id: Volume ID (vol_xxx)
+        :param path: Destination path in volume
+        :param content: File content as bytes
+        :return: Size of uploaded file
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        response = client.put(
+            f"{config.api_url}/volumes/{volume_id}/files/upload",
+            params={"path": path},
+            content=content,
+            headers={"Content-Type": "application/octet-stream"},
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundException(f"Volume '{volume_id}' not found")
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return response.json().get("size", len(content))
+
+    @staticmethod
+    def _download_file(
+        volume_id: str,
+        path: str,
+        **opts: Unpack[ApiParams],
+    ) -> bytes:
+        """
+        Download file content from volume.
+
+        :param volume_id: Volume ID (vol_xxx)
+        :param path: File path in volume
+        :return: File content as bytes
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        response = client.get(
+            f"{config.api_url}/volumes/{volume_id}/files/download",
+            params={"path": path},
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundException(f"Volume '{volume_id}' or file '{path}' not found")
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return response.content
+
+    @staticmethod
+    def _delete_file(
+        volume_id: str,
+        path: str,
+        recursive: bool = False,
+        **opts: Unpack[ApiParams],
+    ) -> bool:
+        """
+        Delete file or directory from volume.
+
+        :param volume_id: Volume ID (vol_xxx)
+        :param path: Path to delete
+        :param recursive: Delete directory recursively
+        :return: True if deleted
+        """
+        config = ConnectionConfig(**opts)
+        api_client = get_api_client(config)
+        client = api_client.get_httpx_client()
+
+        params: dict = {"path": path}
+        if recursive:
+            params["recursive"] = "true"
+
+        response = client.delete(
+            f"{config.api_url}/volumes/{volume_id}/files",
+            params=params,
+            timeout=config.request_timeout,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundException(f"Volume '{volume_id}' or path '{path}' not found")
+
+        err = handle_api_exception(response)
+        if err:
+            raise err
+
+        return True

moru/volume_async/__init__.py

@@ -0,0 +1,5 @@
+"""Asynchronous Volume module."""
+
+from .main import AsyncVolume
+
+__all__ = ["AsyncVolume"]