list_sandboxes
View all Modal sandboxes and their status within a specific app namespace to monitor environments and identify running instances.
Instructions
Lists all Modal sandboxes for a specific app namespace and their current status.
Parameters:
- app_name: Name of the Modal app namespace to list sandboxes for
Returns a list of sandboxes containing:
- sandbox_id: Unique identifier for each sandbox
- sandbox_status: Current state of the sandbox (running/stopped)
This tool is useful for:
- Monitoring active Modal sandbox environments within an app namespace
- Checking which sandboxes are currently running
- Getting sandbox IDs for further management operations
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The handler function that implements the list_sandboxes tool. It retrieves the list of Modal sandboxes for the associated app and constructs SandboxListItem objects with their IDs and statuses (running if poll returns None, stopped otherwise).
async def list_sandboxes(self, ctx:Context) -> List[SandboxListItem]: await ctx.info(f"Listing sandboxes for app '{self.app_name}'...") app = modal.App.lookup(self.app_name, create_if_missing=True) sandbox_list: List[SandboxListItem] = [] async for sandbox in modal.Sandbox.list.aio(app_id=app.app_id): sandbox_status = await sandbox.poll.aio() sandbox_list.append(SandboxListItem( sandbox_id=sandbox.object_id, sandbox_status=SandboxStatus.RUNNING if sandbox_status is None else SandboxStatus.STOPPED, )) await ctx.info(f"Found {len(sandbox_list)} sandboxes") return sandbox_list - Pydantic BaseModel defining the output schema for each item in the list returned by list_sandboxes tool, consisting of sandbox_id and sandbox_status.
class SandboxListItem(BaseModel): sandbox_id: str sandbox_status: SandboxStatus - src/mcp4modal_sandbox/backend/mcp_server.py:111-114 (registration)Registers the list_sandboxes tool with the FastMCP instance, linking the name, description from ToolDescriptions, and the handler method.
mcp_app.tool( name="list_sandboxes", description=ToolDescriptions.LIST_SANDBOXES, )(self.list_sandboxes) - Enum used in SandboxListItem for the sandbox_status field, defining possible statuses returned by the tool.
class SandboxStatus(str, Enum): RUNNING = "running" STOPPED = "stopped" - Tool description string used in the registration of list_sandboxes, providing usage instructions and parameter details.
LIST_SANDBOXES = """ Lists all Modal sandboxes for a specific app namespace and their current status. Parameters: - app_name: Name of the Modal app namespace to list sandboxes for Returns a list of sandboxes containing: - sandbox_id: Unique identifier for each sandbox - sandbox_status: Current state of the sandbox (running/stopped) This tool is useful for: - Monitoring active Modal sandbox environments within an app namespace - Checking which sandboxes are currently running - Getting sandbox IDs for further management operations """