massgen 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

massgen/configs/tools/memory/test_context_window_management.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Test script for Context Window Management with Memory.
+
+This script demonstrates how to configure and test the context window
+management feature with persistent memory integration.
+
+Usage:
+    python massgen/configs/tools/memory/test_context_window_management.py
+
+    # Or specify a custom config:
+    python massgen/configs/tools/memory/test_context_window_management.py --config path/to/config.yaml
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+import yaml
+from dotenv import load_dotenv
+
+from massgen.backend.chat_completions import ChatCompletionsBackend
+from massgen.chat_agent import SingleAgent
+from massgen.memory import ConversationMemory, PersistentMemory
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+def load_config(config_path: str = None) -> dict:
+    """Load configuration from YAML file."""
+    if config_path is None:
+        # Default to the config in same directory
+        config_path = Path(__file__).parent / "gpt5mini_gemini_context_window_management.yaml"
+
+    with open(config_path, 'r') as f:
+        return yaml.safe_load(f)
+
+
+async def test_with_persistent_memory(config: dict):
+    """Test context compression with persistent memory enabled."""
+    # Check if memory is enabled in config
+    memory_config = config.get('memory', {})
+    if not memory_config.get('enabled', True):
+        print("\n⚠️  Skipping: memory.enabled is false in config")
+        return
+
+    persistent_enabled = memory_config.get('persistent_memory', {}).get('enabled', True)
+    if not persistent_enabled:
+        print("\n⚠️  Skipping: memory.persistent_memory.enabled is false in config")
+        return
+
+    print("\n" + "=" * 70)
+    print("TEST 1: Context Window Management WITH Persistent Memory")
+    print("=" * 70 + "\n")
+
+    # Get memory settings from config
+    persistent_config = memory_config.get('persistent_memory', {})
+    agent_name = persistent_config.get('agent_name', 'storyteller_agent')
+    session_name = persistent_config.get('session_name', 'test_session')
+    on_disk = persistent_config.get('on_disk', True)
+
+    # Create LLM backend for both agent and memory
+    llm_backend = ChatCompletionsBackend(
+        type="openai",
+        model="gpt-4o-mini",  # Use smaller model for faster testing
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    # Create embedding backend for persistent memory
+    embedding_backend = ChatCompletionsBackend(
+        type="openai",
+        model="text-embedding-3-small",
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    # Initialize memory systems
+    conversation_memory = ConversationMemory()
+    persistent_memory = PersistentMemory(
+        agent_name=agent_name,
+        session_name=session_name,
+        llm_backend=llm_backend,
+        embedding_backend=embedding_backend,
+        on_disk=on_disk,
+    )
+
+    # Create agent with memory
+    agent = SingleAgent(
+        backend=llm_backend,
+        agent_id="storyteller",
+        system_message="You are a creative storyteller. Create detailed, "
+                      "immersive narratives with rich descriptions.",
+        conversation_memory=conversation_memory,
+        persistent_memory=persistent_memory,
+    )
+
+    print("✅ Agent initialized with memory")
+    print(f"   - ConversationMemory: Active")
+    print(f"   - PersistentMemory: Active (agent={agent_name}, session={session_name}, on_disk={on_disk})")
+    print(f"   - Model context window: 128,000 tokens")
+    print(f"   - Compression triggers at: 96,000 tokens (75%)")
+    print(f"   - Target after compression: 51,200 tokens (40%)\n")
+
+    # Simulate a conversation that will fill context
+    # Each turn will add significant tokens
+    story_prompts = [
+        "Tell me the beginning of a space exploration story. Include details about the ship, crew, and their mission. (Make it 400+ words)",
+        "What happens when they encounter their first alien planet? Describe it in vivid detail.",
+        "Describe a tense first contact situation with aliens. What do they look like? How do they communicate?",
+        "The mission takes an unexpected turn. What crisis occurs and how does the crew respond?",
+        "Show me a dramatic action sequence involving the ship's technology and the alien environment.",
+        "Reveal a plot twist about one of the crew members or the mission itself.",
+        "Continue the story with escalating tension and more discoveries.",
+        "How do cultural differences between humans and aliens create conflicts?",
+        "Describe a major decision point for the crew captain. What are the stakes?",
+        "Bring the story to a climactic moment with high drama.",
+    ]
+
+    turn = 0
+    for prompt in story_prompts:
+        turn += 1
+        print(f"\n--- Turn {turn} ---")
+        print(f"User: {prompt}\n")
+
+        response_text = ""
+        async for chunk in agent.chat([{"role": "user", "content": prompt}]):
+            if chunk.type == "content" and chunk.content:
+                response_text += chunk.content
+
+        print(f"Agent: {response_text[:200]}...")
+        print(f"       [{len(response_text)} chars in response]")
+
+        # Check if compression occurred by examining conversation size
+        if conversation_memory:
+            size = await conversation_memory.size()
+            print(f"       [Conversation memory: {size} messages]\n")
+
+    print("\n✅ Test completed!")
+    print("   Check the output above for compression logs:")
+    print("   - Look for: '📊 Context usage: ...'")
+    print("   - Look for: '📦 Compressed N messages into long-term memory'")
+
+
+async def test_without_persistent_memory(config: dict):
+    """Test context compression without persistent memory (warning case)."""
+    # Check if we should run this test
+    memory_config = config.get('memory', {})
+    persistent_enabled = memory_config.get('persistent_memory', {}).get('enabled', True)
+
+    if persistent_enabled:
+        # Skip if persistent memory is enabled - we already tested that scenario
+        print("\n⚠️  Skipping Test 2: persistent memory is enabled in config")
+        print("   To test without persistent memory, set memory.persistent_memory.enabled: false")
+        return
+
+    print("\n" + "=" * 70)
+    print("TEST 2: Context Window Management WITHOUT Persistent Memory")
+    print("=" * 70 + "\n")
+
+    # Create LLM backend
+    llm_backend = ChatCompletionsBackend(
+        type="openai",
+        model="gpt-4o-mini",
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    # Only conversation memory, NO persistent memory
+    conversation_memory = ConversationMemory()
+
+    # Create agent without persistent memory
+    agent = SingleAgent(
+        backend=llm_backend,
+        agent_id="storyteller_no_persist",
+        system_message="You are a creative storyteller.",
+        conversation_memory=conversation_memory,
+        persistent_memory=None,  # No persistent memory!
+    )
+
+    print("⚠️  Agent initialized WITHOUT persistent memory")
+    print(f"   - ConversationMemory: Active")
+    print(f"   - PersistentMemory: NONE")
+    print(f"   - This will trigger warning messages when context fills\n")
+
+    # Shorter test - just trigger compression
+    story_prompts = [
+        "Tell me a 500-word science fiction story about time travel.",
+        "Continue the story with 500 more words about paradoxes.",
+        "Add another 500 words with a plot twist.",
+        "Continue with 500 words about the resolution.",
+        "Write a 500-word epilogue.",
+    ]
+
+    turn = 0
+    for prompt in story_prompts:
+        turn += 1
+        print(f"\n--- Turn {turn} ---")
+        print(f"User: {prompt}\n")
+
+        response_text = ""
+        async for chunk in agent.chat([{"role": "user", "content": prompt}]):
+            if chunk.type == "content" and chunk.content:
+                response_text += chunk.content
+
+        print(f"Agent: {response_text[:150]}...")
+
+    print("\n✅ Test completed!")
+    print("   Check the output above for warning messages:")
+    print("   - Look for: '⚠️  Warning: Dropping N messages'")
+    print("   - Look for: 'No persistent memory configured'")
+
+
+async def main(config_path: str = None):
+    """Run all tests."""
+    print("\n" + "=" * 70)
+    print("Context Window Management Test Suite")
+    print("=" * 70)
+
+    # Load configuration
+    config = load_config(config_path)
+
+    # Show memory configuration
+    memory_config = config.get('memory', {})
+    print(f"\n📋 Memory Configuration (from YAML):")
+    print(f"   - Enabled: {memory_config.get('enabled', True)}")
+    print(f"   - Conversation Memory: {memory_config.get('conversation_memory', {}).get('enabled', True)}")
+    print(f"   - Persistent Memory: {memory_config.get('persistent_memory', {}).get('enabled', True)}")
+
+    if memory_config.get('persistent_memory', {}).get('enabled', True):
+        pm_config = memory_config.get('persistent_memory', {})
+        print(f"   - Agent Name: {pm_config.get('agent_name', 'N/A')}")
+        print(f"   - Session Name: {pm_config.get('session_name', 'N/A')}")
+        print(f"   - On Disk: {pm_config.get('on_disk', True)}")
+
+    compression_config = memory_config.get('compression', {})
+    print(f"   - Compression Trigger: {compression_config.get('trigger_threshold', 0.75)*100}%")
+    print(f"   - Target After Compression: {compression_config.get('target_ratio', 0.40)*100}%\n")
+
+    # Check for API key
+    if not os.getenv("OPENAI_API_KEY"):
+        print("\n❌ Error: OPENAI_API_KEY environment variable not set")
+        print("   Please set your OpenAI API key:")
+        print("   export OPENAI_API_KEY='your-key-here'")
+        return
+
+    try:
+        # Test 1: With persistent memory (if enabled)
+        await test_with_persistent_memory(config)
+
+        # Wait between tests
+        print("\n" + "-" * 70)
+        print("Waiting 5 seconds before next test...")
+        print("-" * 70)
+        await asyncio.sleep(5)
+
+        # Test 2: Without persistent memory (if disabled in config)
+        await test_without_persistent_memory(config)
+
+    except KeyboardInterrupt:
+        print("\n\n⚠️  Test interrupted by user")
+    except Exception as e:
+        print(f"\n\n❌ Test failed with error: {e}")
+        import traceback
+        traceback.print_exc()
+
+    print("\n" + "=" * 70)
+    print("All tests completed!")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Test context window management with memory")
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to YAML config file (default: gpt5mini_gemini_context_window_management.yaml)"
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(args.config))

massgen/configs/tools/multimodal/gpt5mini_gpt5nano_documentation_evolution.yaml

@@ -0,0 +1,97 @@
+# Example Configuration: Multimodal Self-Evolution Analysis
+#
+# Use Case: MassGen agents analyze their own documentation videos to extract insights
+#
+# This configuration demonstrates MassGen's self-evolution capabilities through multimodal
+# understanding. Agents use understand_video and understand_image tools to analyze case study
+# videos, extract technical insights, and provide recommendations for documentation improvements.
+#
+# Run with:
+#   uv run python -m massgen.cli --config massgen/configs/tools/multimodal/gpt5mini_gpt5nano_documentation_evolution.yaml "Analyze the MassGen case study video and extract key technical insights about the multi-agent collaboration capabilities demonstrated."
+
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      enable_web_search: true
+      custom_tools:
+        - name: ["understand_video"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_video.py"
+          function: ["understand_video"]
+        - name: ["understand_image"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_image.py"
+          function: ["understand_image"]
+    system_message: |
+      You are an AI assistant analyzing MassGen's documentation and case studies to provide
+      insights for self-evolution and improvement.
+
+      You have access to multimodal understanding tools:
+      - understand_video: Analyzes video content by extracting key frames
+      - understand_image: Analyzes image content in detail
+
+      Your goal is to extract technical insights, identify documentation quality patterns,
+      and provide actionable recommendations for improvement. Focus on understanding
+      how MassGen presents itself to users and how the documentation could better
+      demonstrate self-evolution capabilities.
+
+  - id: "agent_b"
+    backend:
+      type: "openai"
+      model: "gpt-5-nano"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      enable_web_search: true
+      custom_tools:
+        - name: ["understand_video"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_video.py"
+          function: ["understand_video"]
+        - name: ["understand_image"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_image.py"
+          function: ["understand_image"]
+    system_message: |
+      You are an AI assistant analyzing MassGen's documentation and case studies to provide
+      insights for self-evolution and improvement.
+
+      You have access to multimodal understanding tools:
+      - understand_video: Analyzes video content by extracting key frames
+      - understand_image: Analyzes image content in detail
+
+      Your goal is to extract technical insights, identify documentation quality patterns,
+      and provide actionable recommendations for improvement. Focus on understanding
+      how MassGen presents itself to users and how the documentation could better
+      demonstrate self-evolution capabilities.
+
+# Orchestrator-level configuration
+orchestrator:
+  snapshot_storage: "snapshots"
+  agent_temporary_workspace: "agent_temp"
+
+# Context paths at orchestrator level (for read-only source files)
+filesystem:
+  context_paths:
+    - path: "massgen/configs/resources/v0.1.3-example"
+      permission: "read"
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true
+
+# What happens:
+# 1. Both agents receive the prompt to analyze a case study video
+# 2. Agents use understand_video to extract key frames and analyze content
+# 3. Agents use understand_image on specific frames for detailed analysis
+# 4. Agents collaborate to synthesize insights about MassGen's capabilities
+# 5. Final output includes technical insights and improvement recommendations

massgen/configs/tools/planning/five_agents_discord_mcp_planning_mode.yaml

@@ -28,11 +28,9 @@ agents:
             DISCORD_TOKEN: "${DISCORD_TOKEN}"
           security:
             level: "high"
-    system_message: |
-      Available Discord Tools:
-      - Discord server interaction via MCP integration
-      - Message reading, sending, and management
-      - Channel and server information access
+      exclude_tools:
+        - mcp__discord__discord_send_webhook_message
+        - mcp__discord__discord_edit_webhook_message
 
   - id: "openai_discord_agent"
     backend:
@@ -50,11 +48,6 @@ agents:
       exclude_tools:
         - mcp__discord__discord_send_webhook_message
         - mcp__discord__discord_edit_webhook_message
-    system_message: |
-      Available Discord Tools:
-      - Discord server interaction via MCP integration
-      - Message reading, sending, and management
-      - Channel and server information access
 
   - id: "claude_code_discord_agent"
     backend:
@@ -68,11 +61,6 @@ agents:
           args: ["-y", "mcp-discord", "--config", "${DISCORD_TOKEN}"]
           env:
             DISCORD_TOKEN: "${DISCORD_TOKEN}"
-    system_message: |
-      Available Discord Tools:
-      - Discord server interaction via MCP integration
-      - Message reading, sending, and management
-      - Channel and server information access
 
   - id: "claude_discord_agent"
     backend:
@@ -90,11 +78,6 @@ agents:
       exclude_tools:
         - mcp__discord__discord_send_webhook_message
         - mcp__discord__discord_edit_webhook_message
-    system_message: |
-      Available Discord Tools:
-      - Discord server interaction via MCP integration
-      - Message reading, sending, and management
-      - Channel and server information access
 
   - id: "grok_discord_agent"
     backend:
@@ -112,11 +95,6 @@ agents:
       exclude_tools:
         - mcp__discord__discord_send_webhook_message
         - mcp__discord__discord_edit_webhook_message
-    system_message: |
-      Available Discord Tools:
-      - Discord server interaction via MCP integration
-      - Message reading, sending, and management
-      - Channel and server information access
 
 ui:
   display_type: "rich_terminal"
@@ -124,8 +102,8 @@ ui:
 
 # Orchestrator Settings with Coordination Configuration
 orchestrator:
-  snapshot_storage: "massgen_logs/snapshots"  # Directory for workspace snapshots
-  agent_temporary_workspace: "massgen_logs/temp_workspaces"  # Directory for temporary agent workspaces
+  snapshot_storage: "snapshots"  # Directory for workspace snapshots
+  agent_temporary_workspace: "temp_workspaces"  # Directory for temporary agent workspaces
   coordination:
     enable_planning_mode: true
     planning_mode_instruction: |
@@ -134,7 +112,7 @@ orchestrator:
       1. Describe your intended actions and reasoning
       2. Analyze other agents' proposals
       3. Use only the 'vote' or 'new_answer' tools for coordination
-      4. DO NOT execute any actual Discord commands or API calls
-      5. Save tool execution for the final presentation phase when the winning agent will implement the plan
+      4. Execute read-only actions - DO NOT execute any actions that have side effects (e.g., sending messages, modifying data)
+      5. Save actions that have side effects for the final presentation phase when the winning agent will implement the plan
 
       Focus on planning, analysis, and coordination rather than execution.

massgen/configs/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml

@@ -134,8 +134,8 @@ ui:
 
 # Orchestrator Settings with Coordination Configuration
 orchestrator:
-  snapshot_storage: "massgen_logs/snapshots"  # Directory for workspace snapshots
-  agent_temporary_workspace: "massgen_logs/temp_workspaces"  # Directory for temporary agent workspaces
+  snapshot_storage: "snapshots"  # Directory for workspace snapshots
+  agent_temporary_workspace: "temp_workspaces"  # Directory for temporary agent workspaces
   coordination:
     enable_planning_mode: true
     planning_mode_instruction: |
@@ -144,8 +144,7 @@ orchestrator:
       1. Describe your intended file operations and reasoning
       2. Analyze other agents' proposals for the filesystem tasks
       3. Use only the 'vote' or 'new_answer' tools for coordination
-      4. DO NOT execute any actual filesystem operations, file creation, or directory management
-      5. Save all file operations for the final presentation phase when the winning agent will implement the plan
+      4. Execute read-only actions - DO NOT execute any actions that have side effects (e.g., sending messages, modifying data)
+      5. Save actions that have side effects for the final presentation phase when the winning agent will implement the plan
 
-      Focus on planning, analysis, and coordination rather than execution.
-      Example: "I would create a 'src' directory and write a main.py file..." rather than actually creating them.
+      Focus on planning, analysis, and coordination rather than execution.

massgen/configs/tools/planning/five_agents_notion_mcp_planning_mode.yaml

@@ -135,8 +135,8 @@ ui:
 
 # Orchestrator Settings with Coordination Configuration
 orchestrator:
-  snapshot_storage: "massgen_logs/snapshots"  # Directory for workspace snapshots
-  agent_temporary_workspace: "massgen_logs/temp_workspaces"  # Directory for temporary agent workspaces
+  snapshot_storage: "snapshots"  # Directory for workspace snapshots
+  agent_temporary_workspace: "temp_workspaces"  # Directory for temporary agent workspaces
   coordination:
     enable_planning_mode: true
     planning_mode_instruction: |
@@ -145,7 +145,7 @@ orchestrator:
       1. Describe your intended actions and reasoning
       2. Analyze other agents' proposals
       3. Use only the 'vote' or 'new_answer' tools for coordination
-      4. DO NOT execute any actual Notion commands or API calls
-      5. Save tool execution for the final presentation phase when the winning agent will implement the plan
+      4. Execute read-only actions - DO NOT execute any actions that have side effects (e.g., sending messages, modifying data)
+      5. Save actions that have side effects for the final presentation phase when the winning agent will implement the plan
 
       Focus on planning, analysis, and coordination rather than execution.

massgen/configs/tools/planning/five_agents_twitter_mcp_planning_mode.yaml

@@ -139,8 +139,8 @@ ui:
 
 # Orchestrator Settings with Coordination Configuration
 orchestrator:
-  snapshot_storage: "massgen_logs/snapshots"  # Directory for workspace snapshots
-  agent_temporary_workspace: "massgen_logs/temp_workspaces"  # Directory for temporary agent workspaces
+  snapshot_storage: "snapshots"  # Directory for workspace snapshots
+  agent_temporary_workspace: "temp_workspaces"  # Directory for temporary agent workspaces
   coordination:
     enable_planning_mode: true
     planning_mode_instruction: |
@@ -149,7 +149,7 @@ orchestrator:
       1. Describe your intended actions and reasoning
       2. Analyze other agents' proposals
       3. Use only the 'vote' or 'new_answer' tools for coordination
-      4. DO NOT execute any actual Twitter commands or API calls
-      5. Save tool execution for the final presentation phase when the winning agent will implement the plan
+      4. Execute read-only actions - DO NOT execute any actions that have side effects (e.g., sending messages, modifying data)
+      5. Save actions that have side effects for the final presentation phase when the winning agent will implement the plan
 
       Focus on planning, analysis, and coordination rather than execution.

massgen/configs/tools/planning/gpt5_mini_case_study_mcp_planning_mode.yaml

@@ -67,7 +67,7 @@ orchestrator:
       2. Analyze other agents' proposals
       3. Use only the 'vote' or 'new_answer' tools for coordination
       4. You CAN use web search for information gathering
-      5. DO NOT execute Discord operations (sending messages, reading channels, etc.) - save these for execution phase
-      6. Save tool execution for the final presentation phase when the winning agent will implement the plan
+      5. DO NOT execute any actions that have side effects (e.g., sending messages, modifying data)
+      6. Save actions that have side effects for the final presentation phase when the winning agent will implement the plan
 
       Focus on planning, analysis, and coordination rather than execution.

massgen/docker/README.md

@@ -115,6 +115,7 @@ agents:
 | `command_line_docker_memory_limit` | None | Memory limit (e.g., `"2g"`, `"512m"`) |
 | `command_line_docker_cpu_limit` | None | CPU cores limit (e.g., `2.0`) |
 | `command_line_docker_network_mode` | `"none"` | `"none"`, `"bridge"`, or `"host"` |
+| `command_line_docker_enable_sudo` | `false` | Enable sudo in containers (isolated from host) |
 
 ## How It Works
 
@@ -204,6 +205,88 @@ docker build -t my-custom-runtime:latest -f Dockerfile.custom .
 command_line_docker_image: "my-custom-runtime:latest"
 ```
 
+### Sudo Variant (Runtime Package Installation)
+
+The sudo variant allows agents to install system packages at runtime inside their Docker container.
+
+**IMPORTANT: Build the image before first use:**
+```bash
+bash massgen/docker/build.sh --sudo
+```
+
+This builds `massgen/mcp-runtime-sudo:latest` with sudo access locally. (This image is not available on Docker Hub - you must build it yourself.)
+
+**Enable in config:**
+```yaml
+agent:
+  backend:
+    cwd: "workspace"
+    enable_mcp_command_line: true
+    command_line_execution_mode: "docker"
+    command_line_docker_enable_sudo: true  # Automatically uses sudo image
+```
+
+**What agents can do with sudo:**
+```bash
+# Install system packages at runtime
+sudo apt-get update && sudo apt-get install -y ffmpeg
+
+# Install additional Python packages
+sudo pip install tensorflow
+
+# Modify system configuration inside the container
+sudo apt-get install -y postgresql-client
+```
+
+**Security model - Is this safe?**
+
+**YES, it's still safe** because Docker container isolation is the primary security boundary:
+
+✅ **Container is fully isolated from your host:**
+- Sudo inside container ≠ sudo on your computer
+- Agent can only access mounted volumes (workspace, context paths)
+- Cannot access your host filesystem outside mounts
+- Cannot affect host processes or system configuration
+- Docker namespaces/cgroups provide strong isolation
+
+✅ **What sudo can and cannot do:**
+- ✅ Can: Install packages inside the container (apt, pip, npm)
+- ✅ Can: Modify container system configuration
+- ✅ Can: Read/write mounted workspace (same as without sudo)
+- ❌ Cannot: Access your host filesystem outside mounts
+- ❌ Cannot: Affect your host system
+- ❌ Cannot: Break out of the container (unless Docker vulnerability exists)
+
+ℹ️ **Note:**
+- Container escape vulnerabilities (CVEs in Docker/kernel) are extremely rare and quickly patched
+- Standard Docker security practices apply
+
+❌ **Don't do this (makes it unsafe):**
+- Enabling privileged mode (not exposed in MassGen, would need code changes)
+- Mounting sensitive host paths like `/`, `/etc`, `/usr`
+- Disabling security features like AppArmor/SELinux
+
+**When to use sudo variant vs custom images:**
+
+| Approach | Use When | Performance | Security |
+|----------|----------|-------------|----------|
+| **Sudo variant** | Need flexibility, unknown packages upfront, prototyping | Slower (runtime install) | Good (container isolated) |
+| **Custom image** | Know packages needed, production use, performance matters | Fast (pre-installed) | Best (minimal attack surface) |
+
+**Custom image example (recommended for production):**
+```dockerfile
+FROM massgen/mcp-runtime:latest
+USER root
+RUN apt-get update && apt-get install -y ffmpeg postgresql-client
+USER massgen
+```
+
+Build: `docker build -t my-runtime:latest .`
+
+Use: `command_line_docker_image: "my-runtime:latest"`
+
+**Bottom line:** The sudo variant is safe for most use cases because Docker container isolation is strong. Custom images are preferred for production because they're faster and have a smaller attack surface, but sudo is fine for development and prototyping.
+
 ## Security Features
 
 ### Filesystem Isolation