lint: ruff clean on src/ and webapp/

Author: User

docs/specifications/sandboxing_technologies.md

@@ -173,19 +173,87 @@ docker run -p 4000:80 myapp
 - CI/CD pipelines
 - Multi-service applications
 
+## Docker Sandbox (docker sandbox + docker agent)
+
+*Added 2026-05-06 for future reference.*
+
+Docker Desktop v0.12+ ships two AI-agent-oriented commands:
+
+### docker sandbox
+Creates VM-based isolated sandbox environments for AI agents. Built-in agent templates:
+
+| Subcommand | Template |
+|---|---|
+| `opencode` | Pre-configured for our fleet CLI tool |
+| `claude` | Claude Code |
+| `codex` | Terminal AI coding agent |
+| `copilot` | GitHub Copilot |
+| `gemini` | Google Gemini CLI |
+| `cagent` | Docker's agent runner (v1.44.0) |
+| `kiro` | Terminal agent |
+| `shell` | Plain shell |
+
+```bash
+# Create a sandbox for opencode
+docker sandbox create opencode --name my-sandbox
+
+# List running sandboxes
+docker sandbox ls
+
+# Exec into a sandbox
+docker sandbox exec my-sandbox -- bash
+
+# Snapshot and restore
+docker sandbox save my-sandbox --template my-template
+docker sandbox create opencode --template my-template
+
+# Clean up
+docker sandbox rm my-sandbox
+```
+
+### docker agent (cagent)
+Docker's AI Agent Runner (internal name: `cagent`, v1.44.0). Runs agents from YAML configs:
+
+```bash
+# Create a new agent config
+docker agent new my-agent --model gemini-2.0-flash
+
+# Run an agent
+docker agent run my-agent
+
+# Run from a YAML file
+docker agent run ./agent.yaml
+
+# Expose as MCP server
+docker agent serve my-agent
+```
+
+### vs. virtualization-mcp sandbox_management
+| Aspect | Docker Sandbox | virtualization-mcp sandbox_management |
+|---|---|---|
+| Isolation | VM-level (full OS) | Container-level (Docker) |
+| Agent support | 8 built-in templates (opencode, claude, etc.) | Custom Python/JS/bash images |
+| Integration | Standalone CLI | MCP tool, fleet-integrated |
+| Snapshot | `docker sandbox save` | `session_destroy` + recreate |
+| Networking | Managed via `docker sandbox network` | `--network` flag |
+
+**Note**: Docker Sandbox overlaps with our existing `sandbox_management` tool but adds VM-level isolation and multi-agent templates. Worth watching for fleet-specific features; not a replacement for our MCP-integrated approach.
+
 ## Comparison Table
 
-| Feature                | venv               | Conda (cenv)       | Docker             |
-|------------------------|-------------------|-------------------|-------------------|
-| Isolation Level       | Python packages   | Python + system   | OS-level          |
-| Package Management    | pip               | conda             | apt/yum/apk/etc.  |
-| Dependencies         | Python only       | Multi-language    | System-wide       |
-| Performance          | Very fast         | Fast              | Slight overhead   |
-| Size                 | Small             | Medium            | Larger            |
-| Startup Time         | Instant           | Fast              | Slower            |
-| Cross-platform       | Yes               | Yes               | Yes (with Docker) |
-| System Requirements  | Python only       | Conda installed   | Docker installed  |
-| Use Case            | Python projects   | Data science      | Deployment        |
+| Feature                | venv               | Conda (cenv)       | Docker Containers  | Docker Sandbox*     |
+|------------------------|-------------------|-------------------|-------------------|-------------------|
+| Isolation Level       | Python packages   | Python + system   | Container-level   | VM-level (full OS) |
+| Package Management    | pip               | conda             | apt/yum/apk/etc.  | Template images     |
+| Dependencies         | Python only       | Multi-language    | System-wide       | Full OS stack       |
+| Performance          | Very fast         | Fast              | Slight overhead   | VM overhead         |
+| Size                 | Small             | Medium            | Larger            | Largest             |
+| Startup Time         | Instant           | Fast              | Slower            | Slowest             |
+| Cross-platform       | Yes               | Yes               | Yes (with Docker) | Yes (Docker Desktop)|
+| System Requirements  | Python only       | Conda installed   | Docker installed  | Docker Desktop v0.12+|
+| Use Case            | Python projects   | Data science      | Deployment        | AI agent sandboxing  |
+
+*\*Docker Sandbox (`docker sandbox` + `docker agent`) added in Docker Desktop v0.12. See section below.*
 
 ## Integration with virtualization-mcp
 

src/virtualization_mcp/__init__.py

@@ -24,7 +24,6 @@
 ]
 
 # Lazy imports to avoid circular imports
-import importlib  # noqa: E402
 
 
 def _lazy_import():

src/virtualization_mcp/all_tools_server.py

@@ -84,7 +84,7 @@ def main() -> int:
     parser.add_argument(
         "--http", action="store_const", const="http", dest="transport", help="Alias for --transport http"
     )
-    parser.add_argument("--host", default="0.0.0.0", help="HTTP host")
+    parser.add_argument("--host", default="0.0.0.0", help="HTTP host")  # noqa: S104
     parser.add_argument("--port", type=int, default=10702, help="HTTP port")
     args = parser.parse_args()
 

src/virtualization_mcp/api/__init__.py

@@ -6,10 +6,9 @@
 """
 
 import logging
-import time
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, Optional, TypeVar, cast
+from typing import Any
 
 from fastmcp import FastMCP
 
@@ -19,7 +18,6 @@
 from ..utils.rate_limiter import RateLimiter
 
 # Import API modules
-from . import documentation
 from .documentation import register_documentation_routes
 
 logger = logging.getLogger(__name__)

src/virtualization_mcp/config.py

@@ -9,6 +9,7 @@
 import sys
 from datetime import datetime
 from pathlib import Path
+from typing import ClassVar
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -22,7 +23,7 @@
     class BaseSettings(BaseModel):
         debug: bool = False
         log_level: str = "INFO"
-        host: str = "0.0.0.0"
+        host: str = "0.0.0.0"  # noqa: S104
         port: int = 10702
 
 
@@ -54,7 +55,7 @@ class Settings(BaseSettings):
     DEBUG: bool = False
 
     # Server configuration (MCP HTTP/SSE: use 10700-10800 per SOTA; 10702 avoids webapp 10700/10701)
-    HOST: str = "0.0.0.0"
+    HOST: str = "0.0.0.0"  # noqa: S104
     PORT: int = Field(default=10702, validation_alias="VIRTUALIZATION_MCP_PORT", description="MCP HTTP/SSE port")
     WEB_PORT: int = 3080  # FastAPI web server port
     WORKERS: int = 1
@@ -210,7 +211,7 @@ def setup_console_handler() -> logging.Handler:
 
     # Color formatter for console
     class ColorFormatter(logging.Formatter):
-        COLORS = {
+        COLORS: ClassVar[dict[str, str]] = {
             "WARNING": "\033[93m",  # Yellow
             "INFO": "\033[92m",  # Green
             "DEBUG": "\033[96m",  # Cyan

src/virtualization_mcp/dual_server.py

@@ -45,7 +45,7 @@ def run_web_server():
     configure_logging()
 
     port = int(os.getenv("WEB_PORT", getattr(settings, "WEB_PORT", 3080)))
-    host = os.getenv("WEB_HOST", "0.0.0.0")
+    host = os.getenv("WEB_HOST", "0.0.0.0")  # noqa: S104
 
     logger.info(f"Starting FastAPI web server on http://{host}:{port}")
     logger.info(f"Web interface: http://localhost:{port}")

src/virtualization_mcp/json_encoder.py

@@ -9,7 +9,7 @@
 from collections.abc import Callable
 from datetime import datetime
 from enum import Enum
-from typing import Any, TypeVar
+from typing import Any, ClassVar, TypeVar
 
 logger = logging.getLogger(__name__)
 
@@ -21,7 +21,7 @@ class VBoxJSONEncoder(json.JSONEncoder):
     """Custom JSON encoder that handles VirtualBox objects and other non-serializable types."""
 
     # Cache for type handlers to improve performance
-    _type_handlers: dict[type, Callable[[Any], Any]] = {}
+    _type_handlers: ClassVar[dict[type, Callable[[Any], Any]]] = {}
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

src/virtualization_mcp/main.py

@@ -23,7 +23,7 @@ def parse_arguments() -> argparse.Namespace:
     """Parse command line arguments."""
     parser = argparse.ArgumentParser(description="VirtualBox MCP Server")
     parser.add_argument("--debug", action="store_true", default=DEBUG, help="Enable debug logging")
-    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to bind the server to")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to bind the server to")  # noqa: S104
     parser.add_argument(
         "--port",
         type=int,

src/virtualization_mcp/plugins/__init__.py

@@ -5,7 +5,6 @@
 """
 
 import logging
-from typing import Optional
 
 from fastmcp import FastMCP
 

src/virtualization_mcp/server_v2/plugins/hyperv_manager.py

@@ -432,7 +432,7 @@ async def shutdown(self) -> None:
             try:
                 await websocket.close()
             except Exception:
-                pass
+                logger.debug("Websocket close failed during shutdown")
 
         await super().shutdown()
         logger.info("Hyper-V Manager plugin stopped")