Sandbox API

Sandbox

Sandbox(config: SandboxConfig, sandbox_id: Optional[str] = None)

              flowchart TD
              ms_enclave.sandbox.boxes.base.Sandbox[Sandbox]

              

              click ms_enclave.sandbox.boxes.base.Sandbox href "" "ms_enclave.sandbox.boxes.base.Sandbox"
            

Abstract base class for all sandbox implementations.

Parameters:

• config

  (SandboxConfig) –

  Sandbox configuration

• sandbox_id

  (Optional[str], default: None ) –

  Optional sandbox ID (will be generated if not provided)

Returned by:

• API 参考  SandboxFactory  create_sandbox

Used by:

• API 参考
  •  SandboxFactory  register_sandbox
  •  Tool  execute

Methods:

• __aenter__ –

  Async context manager entry.

• __aexit__ –

  Async context manager exit.

• add_tool –

  Add a tool to the sandbox.

• cleanup –

  Clean up sandbox resources.

• execute_command –

  Execute a command in the sandbox environment.

• execute_tool –

  Execute a tool with given parameters.

• get_available_tools –

  Get list of available tools.

• get_execution_context –

  Get the execution context for tools (e.g., container, process, etc.).

• get_info –

  Get sandbox information.

• get_tool –

  Get tool instance by type.

• initialize_tools –

  Initialize sandbox tools.

• list_tools –

  List all registered tools compatible with this sandbox.

• start –

  Start the sandbox environment.

• stop –

  Stop the sandbox environment.

• update_status –

  Update sandbox status.

Attributes:

• sandbox_type (SandboxType) –

  Return the sandbox type identifier.

Source code in ms_enclave/sandbox/boxes/base.py

def __init__(self, config: SandboxConfig, sandbox_id: Optional[str] = None):
    """Initialize sandbox.

    Args:
        config: Sandbox configuration
        sandbox_id: Optional sandbox ID (will be generated if not provided)
    """
    self.id = sandbox_id or uuid.ShortUUID(alphabet='23456789abcdefghijkmnopqrstuvwxyz').random(length=8)
    self.config = config
    self.status = SandboxStatus.INITIALIZING
    self.created_at = datetime.now()
    self.updated_at = datetime.now()
    self.metadata: Dict[str, Any] = {}
    self._tools: Dict[str, Tool] = {}

sandbox_type abstractmethod property

sandbox_type: SandboxType

Return the sandbox type identifier.

__aenter__ async

__aenter__()

Async context manager entry.

Source code in ms_enclave/sandbox/boxes/base.py

async def __aenter__(self):
    """Async context manager entry."""
    await self.start()
    return self

__aexit__ async

__aexit__(exc_type, exc_val, exc_tb)

Async context manager exit.

Source code in ms_enclave/sandbox/boxes/base.py

async def __aexit__(self, exc_type, exc_val, exc_tb):
    """Async context manager exit."""
    await self.stop()

add_tool

add_tool(tool: Tool) -> None

Add a tool to the sandbox.

Parameters:

• tool

  (Tool) –

  Tool instance to add

Source code in ms_enclave/sandbox/boxes/base.py

def add_tool(self, tool: Tool) -> None:
    """Add a tool to the sandbox.

    Args:
        tool: Tool instance to add
    """
    if tool.name in self._tools:
        logger.warning(f'Tool {tool.name} is already added to the sandbox')
        return
    if tool.enabled:
        if tool.is_compatible_with_sandbox(self.sandbox_type):
            self._tools[tool.name] = tool
        else:
            logger.warning(
                f"Tool '{tool.name}' requires sandbox types '{tool.required_sandbox_types}' "
                f"but this is a '{self.sandbox_type}' sandbox. "
                f'Compatible types: {SandboxType.get_compatible_types(self.sandbox_type)}'
            )
    else:
        logger.warning(f'Tool {tool.name} is not enabled and cannot be added')

cleanup abstractmethod async

cleanup() -> None

Clean up sandbox resources.

Source code in ms_enclave/sandbox/boxes/base.py

@abc.abstractmethod
async def cleanup(self) -> None:
    """Clean up sandbox resources."""
    pass

execute_command async

execute_command(command: Union[str, List[str]], timeout: Optional[int] = None, stream: bool = True) -> CommandResult

Execute a command in the sandbox environment.

Parameters:

• command

  (Union[str, List[str]]) –

  Command to execute

• timeout

  (Optional[int], default: None ) –

  Optional execution timeout in seconds

• stream

  (bool, default: True ) –

  Whether to stream output (if supported)

Source code in ms_enclave/sandbox/boxes/base.py

async def execute_command(
    self, command: Union[str, List[str]], timeout: Optional[int] = None, stream: bool = True
) -> CommandResult:
    """Execute a command in the sandbox environment.

    Args:
        command: Command to execute
        timeout: Optional execution timeout in seconds
        stream: Whether to stream output (if supported)
    """
    raise NotImplementedError('execute_command must be implemented by subclasses')

execute_tool async

execute_tool(tool_name: str, parameters: Dict[str, Any]) -> ToolResult

Execute a tool with given parameters.

Parameters:

• tool_name

  (str) –

  Tool name

• parameters

  (Dict[str, Any]) –

  Tool parameters

Returns:

• ToolResult –

  Tool execution result

Raises:

• ValueError –

  If tool is not found or not enabled

• TimeoutError –

  If tool execution exceeds timeout

• Exception –

  For other execution errors

Source code in ms_enclave/sandbox/boxes/base.py

async def execute_tool(self, tool_name: str, parameters: Dict[str, Any]) -> ToolResult:
    """Execute a tool with given parameters.

    Args:
        tool_name: Tool name
        parameters: Tool parameters

    Returns:
        Tool execution result

    Raises:
        ValueError: If tool is not found or not enabled
        TimeoutError: If tool execution exceeds timeout
        Exception: For other execution errors
    """
    tool = self.get_tool(tool_name)
    if not tool:
        raise ValueError(f'Tool {tool_name} is not available')
    if not tool.enabled:
        raise ValueError(f'Tool {tool_name} is not enabled')

    result = await tool.execute(sandbox_context=self, **parameters)
    return result

get_available_tools

get_available_tools() -> Dict[str, Any]

Get list of available tools.

Source code in ms_enclave/sandbox/boxes/base.py

def get_available_tools(self) -> Dict[str, Any]:
    """Get list of available tools."""
    return {tool.name: tool.schema for tool in self._tools.values() if tool.enabled}

get_execution_context abstractmethod async

get_execution_context() -> Any

Get the execution context for tools (e.g., container, process, etc.).

Source code in ms_enclave/sandbox/boxes/base.py

@abc.abstractmethod
async def get_execution_context(self) -> Any:
    """Get the execution context for tools (e.g., container, process, etc.)."""
    pass

get_info

get_info() -> SandboxInfo

Get sandbox information.

Returns:

• SandboxInfo –

  Sandbox information

Source code in ms_enclave/sandbox/boxes/base.py

def get_info(self) -> SandboxInfo:
    """Get sandbox information.

    Returns:
        Sandbox information
    """
    return SandboxInfo(
        id=self.id,
        status=self.status,
        type=self.sandbox_type,
        config=self.config.model_dump(exclude_none=True),
        created_at=self.created_at,
        updated_at=self.updated_at,
        metadata=self.metadata,
        available_tools=self.get_available_tools()
    )

get_tool

get_tool(tool_name: str) -> Optional[Tool]

Get tool instance by type.

Parameters:

• tool_name

  (str) –

  Tool name

Returns:

• Optional[Tool] –

  Tool instance or None if not available

Source code in ms_enclave/sandbox/boxes/base.py

def get_tool(self, tool_name: str) -> Optional[Tool]:
    """Get tool instance by type.

    Args:
        tool_name: Tool name

    Returns:
        Tool instance or None if not available
    """
    return self._tools.get(tool_name)

initialize_tools async

initialize_tools() -> None

Initialize sandbox tools.

Source code in ms_enclave/sandbox/boxes/base.py

async def initialize_tools(self) -> None:
    """Initialize sandbox tools."""
    for tool_name, config in self.config.tools_config.items():
        try:
            tool = ToolFactory.create_tool(tool_name, **config)
            self.add_tool(tool)
        except Exception as e:
            logger.error(f'Failed to initialize tool {tool_name}: {e}')

list_tools

list_tools() -> List[str]

List all registered tools compatible with this sandbox.

Returns:

• List[str] –

  List of tool names

Source code in ms_enclave/sandbox/boxes/base.py

def list_tools(self) -> List[str]:
    """
    List all registered tools compatible with this sandbox.

    Returns:
        List of tool names
    """
    return list(self._tools.keys())

start abstractmethod async

start() -> None

Start the sandbox environment.

Source code in ms_enclave/sandbox/boxes/base.py

@abc.abstractmethod
async def start(self) -> None:
    """Start the sandbox environment."""
    pass

stop abstractmethod async

stop() -> None

Stop the sandbox environment.

Source code in ms_enclave/sandbox/boxes/base.py

@abc.abstractmethod
async def stop(self) -> None:
    """Stop the sandbox environment."""
    pass

update_status

update_status(status: SandboxStatus) -> None

Update sandbox status.

Parameters:

• status

  (SandboxStatus) –

  New status

Source code in ms_enclave/sandbox/boxes/base.py

def update_status(self, status: SandboxStatus) -> None:
    """Update sandbox status.

    Args:
        status: New status
    """
    self.status = status
    self.updated_at = datetime.now()

SandboxFactory

Factory for creating sandbox instances.

Methods:

• create_sandbox –

  Create a sandbox instance.

• get_available_types –

  Get list of available sandbox types.

• register_sandbox –

  Register a sandbox class.

create_sandbox classmethod

create_sandbox(sandbox_type: SandboxType, config: Optional[Union[SandboxConfig, Dict]] = None, sandbox_id: Optional[str] = None) -> Sandbox

Create a sandbox instance.

Parameters:

• sandbox_type

  (SandboxType) –

  Sandbox type

• config

  (Optional[Union[SandboxConfig, Dict]], default: None ) –

  Sandbox configuration

• sandbox_id

  (Optional[str], default: None ) –

  Optional sandbox ID

Returns:

• Sandbox –

  Sandbox instance

Raises:

• ValueError –

  If sandbox type is not registered

Source code in ms_enclave/sandbox/boxes/base.py

@classmethod
def create_sandbox(
    cls,
    sandbox_type: SandboxType,
    config: Optional[Union[SandboxConfig, Dict]] = None,
    sandbox_id: Optional[str] = None
) -> Sandbox:
    """Create a sandbox instance.

    Args:
        sandbox_type: Sandbox type
        config: Sandbox configuration
        sandbox_id: Optional sandbox ID

    Returns:
        Sandbox instance

    Raises:
        ValueError: If sandbox type is not registered
    """
    if sandbox_type not in cls._sandboxes:
        raise ValueError(f'Sandbox type {sandbox_type} is not registered')

    # Parse config based on sandbox type
    if not config:
        if sandbox_type == SandboxType.DOCKER:
            config = DockerSandboxConfig()
        elif sandbox_type == SandboxType.DOCKER_NOTEBOOK:
            config = DockerNotebookConfig()
        elif sandbox_type == SandboxType.VOLCENGINE:
            config = VolcengineSandboxConfig()
        else:
            config = SandboxConfig()
    elif isinstance(config, dict):
        if sandbox_type == SandboxType.DOCKER:
            config = DockerSandboxConfig(**config)
        elif sandbox_type == SandboxType.DOCKER_NOTEBOOK:
            config = DockerNotebookConfig(**config)
        elif sandbox_type == SandboxType.VOLCENGINE:
            config = VolcengineSandboxConfig(**config)
        else:
            config = SandboxConfig(**config)

    sandbox_class = cls._sandboxes[sandbox_type]
    return sandbox_class(config, sandbox_id)

get_available_types classmethod

get_available_types() -> List[SandboxType]

Get list of available sandbox types.

Returns:

• List[SandboxType] –

  List of available sandbox types

Source code in ms_enclave/sandbox/boxes/base.py

@classmethod
def get_available_types(cls) -> List[SandboxType]:
    """Get list of available sandbox types.

    Returns:
        List of available sandbox types
    """
    return list(cls._sandboxes.keys())

register_sandbox classmethod

register_sandbox(sandbox_type: SandboxType, sandbox_class: Type[Sandbox])

Register a sandbox class.

Parameters:

• sandbox_type

  (SandboxType) –

  Sandbox type identifier

• sandbox_class

  (Type[Sandbox]) –

  Sandbox class

Source code in ms_enclave/sandbox/boxes/base.py

@classmethod
def register_sandbox(cls, sandbox_type: SandboxType, sandbox_class: Type[Sandbox]):
    """Register a sandbox class.

    Args:
        sandbox_type: Sandbox type identifier
        sandbox_class: Sandbox class
    """
    cls._sandboxes[sandbox_type] = sandbox_class

register_sandbox

register_sandbox(sandbox_type: SandboxType)

Decorator for registering sandboxes.

Parameters:

• sandbox_type

  (SandboxType) –

  Sandbox type identifier

Source code in ms_enclave/sandbox/boxes/base.py

def register_sandbox(sandbox_type: SandboxType):
    """Decorator for registering sandboxes.

    Args:
        sandbox_type: Sandbox type identifier
    """

    def decorator(sandbox_class: Type[Sandbox]):
        SandboxFactory.register_sandbox(sandbox_type, sandbox_class)
        return sandbox_class

    return decorator