terminate_sandbox
Stop running cloud sandboxes to free resources and manage environment lifecycle by providing the sandbox ID.
Instructions
Terminates a Modal sandbox by its ID.
Parameters:
- sandbox_id: The unique identifier of the sandbox to terminate
Returns a SandboxTerminateResponse containing:
- success: Boolean indicating if termination was successful
- message: Detailed message about the termination result
This tool is useful for:
- Stopping running sandboxes that are no longer needed
- Cleaning up resources
- Forcefully ending long-running or stuck sandboxes
- Managing sandbox lifecycle
The tool will:
1. Check if the sandbox exists and is running
2. Send termination signal if running
3. Wait for confirmation of termination
4. Return status of the operation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sandbox_id | Yes |
Implementation Reference
- The handler function that implements the tool logic: fetches the Modal Sandbox by ID, checks if it's running, terminates it if running, waits for termination, and returns a SandboxTerminateResponse.
async def terminate_sandbox(self, sandbox_id: str) -> SandboxTerminateResponse: # Get sandbox from Modal using from_id modal_sandbox = await modal.Sandbox.from_id.aio(sandbox_id) # Check if sandbox is running before terminating sandbox_status = await modal_sandbox.poll.aio() # Terminate the Modal sandbox if sandbox_status is not None: return SandboxTerminateResponse( success=False, message=f"Sandbox {sandbox_id} is not running" ) await modal_sandbox.terminate.aio() # Wait for termination await modal_sandbox.wait.aio(raise_on_termination=False) logger.info(f"Terminated sandbox {sandbox_id}") return SandboxTerminateResponse( success=True, message=f"Sandbox {sandbox_id} terminated successfully" ) - src/mcp4modal_sandbox/backend/mcp_server.py:106-109 (registration)Registers the terminate_sandbox tool with the FastMCP app, specifying name and description, and binding the handler method.
mcp_app.tool( name="terminate_sandbox", description=ToolDescriptions.TERMINATE_SANDBOX, )(self.terminate_sandbox) - Pydantic BaseModel defining the response schema for the terminate_sandbox tool.
class SandboxTerminateResponse(BaseModel): success: bool message: str - Tool description string providing usage instructions, parameters, and return value details for the LLM.
TERMINATE_SANDBOX = """ Terminates a Modal sandbox by its ID. Parameters: - sandbox_id: The unique identifier of the sandbox to terminate Returns a SandboxTerminateResponse containing: - success: Boolean indicating if termination was successful - message: Detailed message about the termination result This tool is useful for: - Stopping running sandboxes that are no longer needed - Cleaning up resources - Forcefully ending long-running or stuck sandboxes - Managing sandbox lifecycle The tool will: 1. Check if the sandbox exists and is running 2. Send termination signal if running 3. Wait for confirmation of termination 4. Return status of the operation """