execute_command
Execute shell commands in isolated Modal sandbox environments to run scripts, test programs, and debug with captured output and timing results.
Instructions
Executes a command in a specified Modal sandbox environment.
Parameters:
- sandbox_id: The unique identifier of the sandbox to run the command in
- command: The shell command to execute (e.g. "python script.py", "ls -la", etc.)
- working_dir: Optional working directory to execute the command from
- timeout: Optional timeout in seconds for command execution
Returns a SandboxExecuteResponse containing:
- stdout: Standard output from the command execution
- stderr: Standard error output from the command execution
- returncode: Exit code of the command (0 typically indicates success)
- execution_time: Time taken to execute the command in seconds
This tool is useful for:
- Running arbitrary commands in isolated sandbox environments
- Testing scripts and programs in clean environments
- Executing programs with specific dependencies
- Debugging environment-specific issues
- Running automated tests in isolation
The tool will:
1. Verify the sandbox exists and is running
2. Execute the specified command in that sandbox
3. Capture all output and timing information
4. Return detailed execution results
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sandbox_id | Yes | ||
| command | Yes | ||
| timeout_seconds | No |
Implementation Reference
- The handler function for the 'execute_command' tool. It retrieves the Modal sandbox by ID, checks if it's running, executes the provided command using modal_sandbox.exec.aio, waits for completion, captures stdout, stderr, returncode, and execution time, then returns a SandboxExecuteResponse.
async def execute_command( self, sandbox_id: str, command: List[str], timeout_seconds: int = 30 ) -> SandboxExecuteResponse: # Get sandbox from Modal using from_id modal_sandbox = await modal.Sandbox.from_id.aio(sandbox_id) # Check if sandbox is running before executing command sandbox_status = await modal_sandbox.poll.aio() if sandbox_status is not None: raise ToolError(f"Sandbox {sandbox_id} is not running") start_time = time() result = await modal_sandbox.exec.aio(*command, timeout=timeout_seconds) await result.wait.aio() execution_time = time() - start_time # Get output from the sandbox stdout = result.stdout.read() if result.stdout else "" stderr = result.stderr.read() if result.stderr else "" returncode = result.returncode logger.info(f"Executed command in sandbox {sandbox_id}: {' '.join(command)}") return SandboxExecuteResponse( stdout=stdout, stderr=stderr, returncode=returncode, execution_time=execution_time ) - src/mcp4modal_sandbox/backend/mcp_server.py:116-119 (registration)The registration of the 'execute_command' tool in the FastMCP app using mcp_app.tool, linking the name, description from ToolDescriptions, and the handler self.execute_command.
mcp_app.tool( name="execute_command", description=ToolDescriptions.EXECUTE_COMMAND, )(self.execute_command) - The tool description string for 'execute_command', used in registration, which serves as the schema documentation for inputs and outputs.
EXECUTE_COMMAND = """ Executes a command in a specified Modal sandbox environment. Parameters: - sandbox_id: The unique identifier of the sandbox to run the command in - command: The shell command to execute (e.g. "python script.py", "ls -la", etc.) - working_dir: Optional working directory to execute the command from - timeout: Optional timeout in seconds for command execution Returns a SandboxExecuteResponse containing: - stdout: Standard output from the command execution - stderr: Standard error output from the command execution - returncode: Exit code of the command (0 typically indicates success) - execution_time: Time taken to execute the command in seconds This tool is useful for: - Running arbitrary commands in isolated sandbox environments - Testing scripts and programs in clean environments - Executing programs with specific dependencies - Debugging environment-specific issues - Running automated tests in isolation The tool will: 1. Verify the sandbox exists and is running 2. Execute the specified command in that sandbox 3. Capture all output and timing information 4. Return detailed execution results """