Skip to content

Manager API

SandboxManager 

SandboxManager(config: Optional[SandboxManagerConfig] = None, **kwargs)


              flowchart TD
              ms_enclave.sandbox.manager.base.SandboxManager[SandboxManager]

              

              click ms_enclave.sandbox.manager.base.SandboxManager href "" "ms_enclave.sandbox.manager.base.SandboxManager"

Abstract base class for sandbox managers.

Parameters:

  • config

    (Optional[SandboxManagerConfig], default: None ) –

    Sandbox manager configuration

Returned by:

Methods:

Source code in ms_enclave/sandbox/manager/base.py 
25
26
27
28
29
30
31
32
33
34
35
36
def __init__(self, config: Optional[SandboxManagerConfig] = None, **kwargs):
    """Initialize the sandbox manager.

    Args:
        config: Sandbox manager configuration
    """
    self.config = config or SandboxManagerConfig()
    self._running = False
    self._sandboxes: Dict[str, 'Sandbox'] = {}
    self._sandbox_pool: Deque[str] = deque()
    self._pool_lock = asyncio.Lock()
    self._pool_initialized = False

__aenter__ async 

__aenter__()

Async context manager entry.

Source code in ms_enclave/sandbox/manager/base.py 
208
209
210
211
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/manager/base.py 
213
214
215
async def __aexit__(self, exc_type, exc_val, exc_tb):
    """Async context manager exit."""
    await self.stop()

cleanup_all_sandboxes abstractmethod async 

cleanup_all_sandboxes() -> None

Clean up all sandboxes.

Source code in ms_enclave/sandbox/manager/base.py 
160
161
162
163
@abstractmethod
async def cleanup_all_sandboxes(self) -> None:
    """Clean up all sandboxes."""
    pass

create_sandbox abstractmethod async 

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

Create a new sandbox.

Parameters:

  • sandbox_type

    (SandboxType) –

    Type of sandbox to create

  • config

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

    Sandbox configuration

  • sandbox_id

    (Optional[str], default: None ) –

    Optional sandbox ID

Returns:

  • str –

    Sandbox ID

Raises:

Source code in ms_enclave/sandbox/manager/base.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@abstractmethod
async def create_sandbox(
    self,
    sandbox_type: SandboxType,
    config: Optional[Union[SandboxConfig, Dict]] = None,
    sandbox_id: Optional[str] = None
) -> str:
    """Create a new sandbox.

    Args:
        sandbox_type: Type of sandbox to create
        config: Sandbox configuration
        sandbox_id: Optional sandbox ID

    Returns:
        Sandbox ID

    Raises:
        ValueError: If sandbox type is not supported
        RuntimeError: If sandbox creation fails
    """
    pass

delete_sandbox abstractmethod async 

delete_sandbox(sandbox_id: str) -> bool

Delete a sandbox.

Parameters:

  • sandbox_id

    (str) –

    Sandbox ID

Returns:

  • bool –

    True if deleted successfully, False if not found

Source code in ms_enclave/sandbox/manager/base.py 
107
108
109
110
111
112
113
114
115
116
117
@abstractmethod
async def delete_sandbox(self, sandbox_id: str) -> bool:
    """Delete a sandbox.

    Args:
        sandbox_id: Sandbox ID

    Returns:
        True if deleted successfully, False if not found
    """
    pass

execute_tool abstractmethod async 

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

Execute tool in sandbox.

Parameters:

  • sandbox_id

    (str) –

    Sandbox ID

  • tool_name

    (str) –

    Tool name to execute

  • parameters

    (Dict[str, Any]) –

    Tool parameters

Returns:

  • ToolResult –

    Tool execution result

Raises:

Source code in ms_enclave/sandbox/manager/base.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
@abstractmethod
async def execute_tool(self, sandbox_id: str, tool_name: str, parameters: Dict[str, Any]) -> ToolResult:
    """Execute tool in sandbox.

    Args:
        sandbox_id: Sandbox ID
        tool_name: Tool name to execute
        parameters: Tool parameters

    Returns:
        Tool execution result

    Raises:
        ValueError: If sandbox or tool not found
    """
    pass

execute_tool_in_pool abstractmethod async 

execute_tool_in_pool(tool_name: str, parameters: Dict[str, Any], timeout: Optional[float] = None) -> ToolResult

Execute tool using an available sandbox from the pool.

Uses FIFO queue to get an idle sandbox, marks it as busy during execution, then returns it to the pool as idle.

Parameters:

  • tool_name

    (str) –

    Tool name to execute

  • parameters

    (Dict[str, Any]) –

    Tool parameters

  • timeout

    (Optional[float], default: None ) –

    Optional timeout for waiting for available sandbox

Returns:

  • ToolResult –

    Tool execution result

Raises:

  • ValueError –

    If pool is empty or no sandbox available

  • TimeoutError –

    If timeout waiting for available sandbox

Source code in ms_enclave/sandbox/manager/base.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
@abstractmethod
async def execute_tool_in_pool(
    self, tool_name: str, parameters: Dict[str, Any], timeout: Optional[float] = None
) -> ToolResult:
    """Execute tool using an available sandbox from the pool.

    Uses FIFO queue to get an idle sandbox, marks it as busy during execution,
    then returns it to the pool as idle.

    Args:
        tool_name: Tool name to execute
        parameters: Tool parameters
        timeout: Optional timeout for waiting for available sandbox

    Returns:
        Tool execution result

    Raises:
        ValueError: If pool is empty or no sandbox available
        TimeoutError: If timeout waiting for available sandbox
    """
    pass

get_sandbox_info abstractmethod async 

get_sandbox_info(sandbox_id: str) -> Optional[SandboxInfo]

Get sandbox information.

Parameters:

  • sandbox_id

    (str) –

    Sandbox ID

Returns:

  • Optional[SandboxInfo] –

    Sandbox information or None if not found

Source code in ms_enclave/sandbox/manager/base.py 
71
72
73
74
75
76
77
78
79
80
81
@abstractmethod
async def get_sandbox_info(self, sandbox_id: str) -> Optional[SandboxInfo]:
    """Get sandbox information.

    Args:
        sandbox_id: Sandbox ID

    Returns:
        Sandbox information or None if not found
    """
    pass

get_sandbox_tools abstractmethod async 

get_sandbox_tools(sandbox_id: str) -> Dict[str, Any]

Get available tools for a sandbox.

Parameters:

  • sandbox_id

    (str) –

    Sandbox ID

Returns:

  • Dict[str, Any] –

    Dictionary of available tool types, e.g., {"tool_name": tool_schema}

Raises:

Source code in ms_enclave/sandbox/manager/base.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
@abstractmethod
async def get_sandbox_tools(self, sandbox_id: str) -> Dict[str, Any]:
    """Get available tools for a sandbox.

    Args:
        sandbox_id: Sandbox ID

    Returns:
        Dictionary of available tool types, e.g., {"tool_name": tool_schema}

    Raises:
        ValueError: If sandbox not found
    """
    pass

get_stats abstractmethod async 

get_stats() -> Dict[str, Any]

Get manager statistics.

Returns:

Source code in ms_enclave/sandbox/manager/base.py 
151
152
153
154
155
156
157
158
@abstractmethod
async def get_stats(self) -> Dict[str, Any]:
    """Get manager statistics.

    Returns:
        Statistics dictionary
    """
    pass

initialize_pool abstractmethod async 

initialize_pool(pool_size: Optional[int] = None, sandbox_type: Optional[SandboxType] = None, config: Optional[Union[SandboxConfig, Dict]] = None) -> List[str]

Initialize sandbox pool.

Parameters:

  • pool_size

    (Optional[int], default: None ) –

    Number of sandboxes in pool (uses config if not provided)

  • sandbox_type

    (Optional[SandboxType], default: None ) –

    Type of sandbox to create

  • config

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

    Sandbox configuration (uses config.sandbox_config if not provided)

Returns:

  • List[str] –

    List of created sandbox IDs

Source code in ms_enclave/sandbox/manager/base.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
@abstractmethod
async def initialize_pool(
    self,
    pool_size: Optional[int] = None,
    sandbox_type: Optional[SandboxType] = None,
    config: Optional[Union[SandboxConfig, Dict]] = None
) -> List[str]:
    """Initialize sandbox pool.

    Args:
        pool_size: Number of sandboxes in pool (uses config if not provided)
        sandbox_type: Type of sandbox to create
        config: Sandbox configuration (uses config.sandbox_config if not provided)

    Returns:
        List of created sandbox IDs
    """
    pass

list_sandboxes abstractmethod async 

list_sandboxes(status_filter: Optional[SandboxStatus] = None) -> List[SandboxInfo]

List all sandboxes.

Parameters:

  • status_filter

    (Optional[SandboxStatus], default: None ) –

    Optional status filter

Returns:

  • List[SandboxInfo] –

    List of sandbox information

Source code in ms_enclave/sandbox/manager/base.py 
83
84
85
86
87
88
89
90
91
92
93
@abstractmethod
async def list_sandboxes(self, status_filter: Optional[SandboxStatus] = None) -> List[SandboxInfo]:
    """List all sandboxes.

    Args:
        status_filter: Optional status filter

    Returns:
        List of sandbox information
    """
    pass

start abstractmethod async 

start() -> None

Start the sandbox manager.

Source code in ms_enclave/sandbox/manager/base.py 
38
39
40
41
@abstractmethod
async def start(self) -> None:
    """Start the sandbox manager."""
    pass

stop abstractmethod async 

stop() -> None

Stop the sandbox manager.

Source code in ms_enclave/sandbox/manager/base.py 
43
44
45
46
@abstractmethod
async def stop(self) -> None:
    """Stop the sandbox manager."""
    pass

stop_sandbox abstractmethod async 

stop_sandbox(sandbox_id: str) -> bool

Stop a sandbox.

Parameters:

  • sandbox_id

    (str) –

    Sandbox ID

Returns:

  • bool –

    True if stopped successfully, False if not found

Source code in ms_enclave/sandbox/manager/base.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
@abstractmethod
async def stop_sandbox(self, sandbox_id: str) -> bool:
    """Stop a sandbox.

    Args:
        sandbox_id: Sandbox ID

    Returns:
        True if stopped successfully, False if not found
    """
    pass

SandboxManagerFactory

Factory for creating sandbox managers.

Methods:

create_manager classmethod 

create_manager(manager_type: Optional[SandboxManagerType] = None, config: Optional[SandboxManagerConfig] = None, **kwargs: Any) -> SandboxManager

Create a sandbox manager instance.

Parameters:

  • manager_type

    (Optional[SandboxManagerType], default: None ) –

    Type of manager to create

  • config

    (Optional[SandboxManagerConfig], default: None ) –

    Manager configuration

  • **kwargs

    (Any, default: {} ) –

    Additional manager-specific parameters

Returns:

Raises:

  • ValueError –

    If manager type is not registered

Source code in ms_enclave/sandbox/manager/base.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
@classmethod
def create_manager(
    cls,
    manager_type: Optional[SandboxManagerType] = None,
    config: Optional[SandboxManagerConfig] = None,
    **kwargs: Any
) -> SandboxManager:
    """Create a sandbox manager instance.

    Args:
        manager_type: Type of manager to create
        config: Manager configuration
        **kwargs: Additional manager-specific parameters

    Returns:
        Sandbox manager instance

    Raises:
        ValueError: If manager type is not registered
    """
    if not manager_type:
        api_url = config.base_url if config else kwargs.get('base_url')
        if api_url:
            manager_type = SandboxManagerType.HTTP
        else:
            manager_type = SandboxManagerType.LOCAL

    if manager_type not in cls._registry:
        raise ValueError(
            f"Sandbox manager type '{manager_type}' not registered. "
            f'Available types: {list(cls._registry.keys())}'
        )

    manager_class = cls._registry[manager_type]
    return manager_class(config=config, **kwargs)

get_registered_types classmethod 

get_registered_types() -> List[SandboxManagerType]

Get list of registered manager types.

Returns:

  • List[SandboxManagerType] –

    List of registered manager types

Source code in ms_enclave/sandbox/manager/base.py 
269
270
271
272
273
274
275
276
@classmethod
def get_registered_types(cls) -> List[SandboxManagerType]:
    """Get list of registered manager types.

    Returns:
        List of registered manager types
    """
    return list(cls._registry.keys())

register classmethod 

register(manager_type: SandboxManagerType, manager_class: type) -> None

Register a sandbox manager class.

Parameters:

  • manager_type

    (SandboxManagerType) –

    Manager type to register

  • manager_class

    (type) –

    Manager class to register

Source code in ms_enclave/sandbox/manager/base.py 
223
224
225
226
227
228
229
230
231
@classmethod
def register(cls, manager_type: SandboxManagerType, manager_class: type) -> None:
    """Register a sandbox manager class.

    Args:
        manager_type: Manager type to register
        manager_class: Manager class to register
    """
    cls._registry[manager_type] = manager_class

register_manager 

register_manager(manager_type: SandboxManagerType) -> Callable[..., type]

Decorator to register a sandbox manager class.

Parameters:

  • manager_type

    (SandboxManagerType) –

    Manager type to register

Returns:

Source code in ms_enclave/sandbox/manager/base.py 
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
def register_manager(manager_type: SandboxManagerType) -> Callable[..., type]:
    """Decorator to register a sandbox manager class.

    Args:
        manager_type: Manager type to register

    Returns:
        Decorator function
    """

    def decorator(manager_class: type) -> type:
        SandboxManagerFactory.register(manager_type, manager_class)
        return manager_class

    return decorator