launch_sandbox
Launch isolated Python sandboxes with configurable dependencies, GPU support, and environment variables for testing, ML workloads, and secure code execution.
Instructions
Launches a new Modal sandbox with specified configuration.
Parameters:
- python_version: Python version to use (default: "3.12")
- pip_packages: List of pip packages to install
- apt_packages: List of apt packages to install
- timeout_seconds: Maximum runtime in seconds (default: 3600)
- cpu: CPU cores allocated (default: 1.0)
- memory: Memory in MB allocated (default: 1024)
- secrets: Dictionary of environment variables to inject (creates new secret)
- volumes: Dictionary of volumes to mount in sandbox, where the key is the path in the sandbox and the value is the name of the volume
- workdir: Working directory in sandbox (default: "/")
- gpu_type: Type of GPU to use (optional). Supported types:
* T4: Entry-level GPU, good for inference
* L4: Mid-range GPU, good for general ML tasks
* A10G: High-performance GPU, good for training
* A100-40GB: High-end GPU with 40GB memory
* A100-80GB: High-end GPU with 80GB memory
* L40S: Latest generation GPU, good for ML workloads
* H100: Latest generation high-end GPU
* H200: Latest generation flagship GPU
* B200: Latest generation enterprise GPU
- gpu_count: Number of GPUs to use (optional, default: 1)
* A10G supports up to 4 GPUs
* Other types support up to 8 GPUs
Returns a SandboxLaunchResponse containing:
- sandbox_id: Unique identifier for the sandbox
- status: Current status of the sandbox
- python_version: Python version installed
- pip_packages: List of pip packages installed
- apt_packages: List of apt packages installed
- preloaded_secrets: List of predefined secrets injected from Modal dashboard
This tool is useful for:
- Creating isolated Python environments
- Running code with specific dependencies
- Testing in clean environments
- Executing long-running tasks
- Running GPU-accelerated workloads
- Training machine learning models
- Running inference on large models
Secrets Management:
- Use 'secrets' parameter to create new secrets with key-value pairs
- Use 'inject_predefined_secrets' to reference existing secrets from Modal dashboard
- Predefined secrets are applied after custom secrets, so they can override values
- Access secrets as environment variables in your sandbox code using os.environ
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| python_version | No | 3.12 | |
| pip_packages | No | ||
| apt_packages | No | ||
| timeout_seconds | No | ||
| cpu | No | ||
| memory | No | ||
| secrets | No | ||
| volumes | No | ||
| workdir | No | /home/solver | |
| gpu_type | No | ||
| gpu_count | No |
Implementation Reference
- The handler function that launches a new Modal sandbox. Builds a custom image with specified Python version, pip/apt packages, handles secrets and volumes, configures GPU if provided, creates the sandbox using modal.Sandbox.create.aio, and returns a SandboxLaunchResponse with sandbox_id and other details.
async def launch_sandbox( self, python_version: str = "3.12", pip_packages: List[str] = None, apt_packages: List[str] = None, timeout_seconds: int = 600, cpu: float = 2.0, memory: int = 4096, secrets: Dict[str, str] = None, volumes: Dict[str, str] = None, workdir: str = "/home/solver", gpu_type: Optional[GPUType] = None, gpu_count: Optional[int] = None, ) -> SandboxLaunchResponse: pip_packages = pip_packages or [] apt_packages = apt_packages or [] secrets = secrets or {} inject_predefined_secrets = self.preloaded_secrets or [] # Build the image with Python version and dependencies image = modal.Image.debian_slim(python_version=python_version) # Install system dependencies if apt_packages: image = image.apt_install(*apt_packages) # Install Python packages if pip_packages: image = image.pip_install(*pip_packages) # Create secrets for environment variables (the proper Modal way) modal_secrets = [] if secrets: secret = modal.Secret.from_dict(secrets) modal_secrets.append(secret) if inject_predefined_secrets: for secret_name in inject_predefined_secrets: secret = modal.Secret.from_name(secret_name) modal_secrets.append(secret) modal_volumes = {} if volumes: for volume_path, volume_name in volumes.items(): modal_volumes[volume_path] = modal.Volume.from_name(volume_name, create_if_missing=True) # Configure GPU if specified gpu = None if gpu_type: if gpu_count: gpu = f"{gpu_type.value}:{gpu_count}" else: gpu = gpu_type.value # Get or create Modal app for the specified namespace app = modal.App.lookup(self.app_name, create_if_missing=True) # Create sandbox with Modal with modal.enable_output(): logger.info(f"Creating sandbox with Python {python_version} in app '{self.app_name}'" + (f" and GPU {gpu}" if gpu else "")) sandbox = await modal.Sandbox.create.aio( "/bin/bash", image=image, app=app, timeout=timeout_seconds, cpu=cpu, memory=memory, secrets=modal_secrets, volumes=modal_volumes, workdir=workdir, gpu=gpu ) # Get the Modal-assigned ID sandbox_id = sandbox.object_id logger.info(f"Launched sandbox {sandbox_id} with Python {python_version}") return SandboxLaunchResponse( sandbox_id=sandbox_id, status="running", python_version=python_version, pip_packages=pip_packages, apt_packages=apt_packages, preloaded_secrets=inject_predefined_secrets, ) - Multiline string defining the tool description, parameters, return values, and usage instructions for the launch_sandbox tool schema.
LAUNCH_SANDBOX = """ Launches a new Modal sandbox with specified configuration. Parameters: - python_version: Python version to use (default: "3.12") - pip_packages: List of pip packages to install - apt_packages: List of apt packages to install - timeout_seconds: Maximum runtime in seconds (default: 3600) - cpu: CPU cores allocated (default: 1.0) - memory: Memory in MB allocated (default: 1024) - secrets: Dictionary of environment variables to inject (creates new secret) - volumes: Dictionary of volumes to mount in sandbox, where the key is the path in the sandbox and the value is the name of the volume - workdir: Working directory in sandbox (default: "/") - gpu_type: Type of GPU to use (optional). Supported types: * T4: Entry-level GPU, good for inference * L4: Mid-range GPU, good for general ML tasks * A10G: High-performance GPU, good for training * A100-40GB: High-end GPU with 40GB memory * A100-80GB: High-end GPU with 80GB memory * L40S: Latest generation GPU, good for ML workloads * H100: Latest generation high-end GPU * H200: Latest generation flagship GPU * B200: Latest generation enterprise GPU - gpu_count: Number of GPUs to use (optional, default: 1) * A10G supports up to 4 GPUs * Other types support up to 8 GPUs Returns a SandboxLaunchResponse containing: - sandbox_id: Unique identifier for the sandbox - status: Current status of the sandbox - python_version: Python version installed - pip_packages: List of pip packages installed - apt_packages: List of apt packages installed - preloaded_secrets: List of predefined secrets injected from Modal dashboard This tool is useful for: - Creating isolated Python environments - Running code with specific dependencies - Testing in clean environments - Executing long-running tasks - Running GPU-accelerated workloads - Training machine learning models - Running inference on large models Secrets Management: - Use 'secrets' parameter to create new secrets with key-value pairs - Use 'inject_predefined_secrets' to reference existing secrets from Modal dashboard - Predefined secrets are applied after custom secrets, so they can override values - Access secrets as environment variables in your sandbox code using os.environ """ - src/mcp4modal_sandbox/backend/mcp_server.py:101-104 (registration)Tool registration using fastmcp.tool decorator, specifying name and description, binding to the launch_sandbox handler method.
mcp_app.tool( name="launch_sandbox", description=ToolDescriptions.LAUNCH_SANDBOX, )(self.launch_sandbox)