Docker Agent

​

Overview

First time here? Complete the Setup guide first to install GAIA and its dependencies.

​

Quick Start

​

Prerequisites

1. Docker Installation (Required): Docker Engine or Desktop: Download from docker.com
2. GAIA Installation: Follow the Setup guide, then install with MCP extras:
   Copy

   uv pip install "amd-gaia[mcp]"
   
3. Download Required Model: The Docker agent uses the Qwen3-Coder-30B-A3B-Instruct-GGUF model for reliable Dockerfile generation and application analysis. Use the Lemonade server’s model manager to download it:
   1. Start Lemonade server with extended context size: lemonade-server serve --ctx-size 8192
   2. Open the model manager in your browser (typically http://localhost:8000)
   3. Search for and download: Qwen3-Coder-30B-A3B-Instruct-GGUF
   Note: The model is over 17GB and can take a while to download depending on your internet connection. It provides excellent results for Dockerfile generation and application analysis. Important: The Docker agent requires a higher context size (8192) than the default (4096) to handle complex application analysis and Dockerfile generation. For more details on Lemonade Server CLI options, see the Lemonade Server documentation.

​

Verify Installation

docker --version

gaia --version

gaia docker "create a Dockerfile for my app" -d ./app

​

Basic Usage

gaia docker "create a Dockerfile for my application" -d ./app

gaia docker "create a Dockerfile for my application and then build and run the container" -d ./app

​

Architecture Overview

​

Key Components

1. DockerAgent (src/gaia/agents/docker/agent.py)
   • Core agent that processes natural language queries
   • Analyzes application structure and dependencies
   • Uses LLM to generate appropriate Dockerfiles
   • Registers four main tools: analyze_directory, generate_dockerfile, build_image, run_container
2. DockerApp (src/gaia/apps/docker/app.py)
   • Application wrapper for the DockerAgent
   • Provides CLI interface and user interaction
   • Formats output for user display
   • Displays next steps after Dockerfile generation
3. GAIA Docker CLI (gaia docker command)
   • Easy command-line interface for Docker operations
   • Supports natural language queries with directory context
   • Automatically manages agent lifecycle
   • No coding required - just describe what you need

​

How It Works

1. Directory Analysis: Scans application structure, detects frameworks, identifies dependencies
2. Context Building: Creates detailed application context for the LLM
3. Natural Language Processing: LLM interprets user intent and requirements
4. Dockerfile Generation: Creates appropriate Dockerfile with best practices
5. Next Steps Guidance: Provides build and run commands

​

Usage Examples

​

Natural Language Commands

gaia docker "create a Dockerfile for my application" -d ./app

• Create just a Dockerfile (analyzes app, generates and saves Dockerfile)
• Build the Docker image (if you ask it to build)
• Run the container (if you ask it to run)
• Or do all three steps in sequence

​

GitHub Copilot Integration

​

Prerequisites

1. Start Lemonade Server with Extended Context:
   Copy

   lemonade-server serve --ctx-size 8192
   
   Note: The extended context size is required for handling complex Docker queries through Copilot.
2. Start GAIA MCP Bridge:
   Copy

   gaia mcp start --port 8080
   
3. Configure VSCode MCP Settings: Add to your VSCode mcp.json (typically in .vscode/mcp.json):
   Copy

   {
       "servers": {
           "gaia-docker": {
               "url": "http://localhost:8080/mcp",
               "type": "http"
           }
       },
       "inputs": []
   }
   
4. Restart VSCode to load the MCP configuration

​

Usage with Copilot

# Ask Copilot to containerize your application in as simple as
"use #gaia-docker with my app"

​

Workflow

1. MCP Bridge: Acts as the intermediary between VSCode/Copilot and GAIA agents
2. Context Awareness: The agent can access your project files and dependencies
3. Interactive Generation: Copilot presents the Dockerfile and next steps inline
4. Iterative Refinement: Continue the conversation to adjust the Dockerfile as needed

​

Integration Methods

​

1. Python API (Direct Integration)

from gaia.agents.docker.agent import DockerAgent

# Initialize and execute
agent = DockerAgent(model_id="Qwen3-Coder-30B-A3B-Instruct-GGUF", silent_mode=True)
result = agent.process_query("create a Dockerfile for my Flask app in directory: ./app")

if result['status'] == 'success':
    print(f"Steps taken: {result['steps_taken']}")
    # Extract Dockerfile content from conversation
    for msg in result.get('conversation', []):
        if msg.get('role') == 'system' and 'dockerfile_content' in msg.get('content', {}):
            print("Dockerfile generated successfully")

​

2. MCP Server (HTTP/JSON-RPC Integration)

gaia mcp docker --port 8080

• The MCP interface currently performs the complete workflow: analyze → create Dockerfile → build image → run container
• This is ideal for automation tools that need full containerization in a single operation
• Future versions will support more granular control (e.g., just creating Dockerfile without building)
• For granular control now, use the CLI interface which supports individual operations

{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "gaia.docker",
        "arguments": {
            "query": "create a Dockerfile for this application",
            "directory": "./app"
        }
    }
}

• MCP Documentation - Complete MCP bridge reference
• n8n Integration Guide - Workflow automation examples

​

Key Features

​

Automatic Application Analysis

• Framework identification (Flask, Django, FastAPI, etc.)
• Python version requirements
• Dependencies from requirements.txt or pyproject.toml
• Application structure and entry points
• Port requirements for web applications

​

Intelligent Dockerfile Generation

• Appropriate base images (Python official images)
• Dependency installation (pip install from requirements.txt)
• Working directory setup
• Application file copying
• Port exposure for web apps
• Runtime commands (ENTRYPOINT or CMD)
• Best practices (non-root user, layer optimization)

​

Multi-Step Workflow

1. Analyze: Scan application directory and identify structure
2. Generate: Create appropriate Dockerfile
3. Validate: Check Dockerfile syntax and completeness
4. Guidance: Provide next steps for build and run

​

Next Steps Guidance

• Build command with appropriate image tag
• Run command with port mappings and necessary flags
• Contextual tips based on application type

​

Command Reference

​

Basic Command Structure

gaia docker "command" [OPTIONS]

​

Available Options

​

Troubleshooting

​

Common Issues and Solutions

​

”Docker Not Installed”

docker --version

​

”Lemonade Server Not Running”

lemonade-server serve

curl http://localhost:8000/health

​

“No Dockerfile Generated”

1. Check that your application has identifiable structure (e.g., requirements.txt, app.py)
2. Ensure the Lemonade server is running
3. Try a more specific query describing your application type
4. Check the agent logs for error messages

​

”Model Not Found”

1. Open Lemonade UI: http://localhost:8000
2. Check Models section for Qwen3-Coder-30B-A3B-Instruct-GGUF

​

MCP Integration Issues

gaia mcp status

gaia mcp stop

gaia mcp start

​

Debug Mode

tail -f gaia.log

tail -f gaia.mcp.log

​

Best Practices

1. Organize Application: Include requirements.txt/pyproject.toml, clear entry point (app.py), logical structure
2. Review Output: Verify base image, dependencies, ports, and runtime commands before building
3. Test Incrementally: Generate → Review → Build → Test container in sequence
4. Use Natural Language: When using GitHub Copilot integration, simple queries like "use #gaia-docker with my app" work well

​

Limitations

• Single-language support: Primarily focused on Python applications
• Simple configurations: Best for straightforward containerization scenarios
• No multi-stage builds: Generated Dockerfiles use single-stage builds
• Limited customization: Advanced Docker features may require manual editing
• No docker-compose: Does not generate docker-compose.yml files

​

Testing Your Integration

from gaia.agents.docker.agent import DockerAgent

agent = DockerAgent(silent_mode=True)
result = agent.process_query("create a Dockerfile for Flask app in: ./app")
print("✅ Success!" if result['status'] == 'success' else "❌ Failed")

gaia mcp start && python tests/mcp/test_mcp_docker.py

​

See Also

• GAIA CLI Documentation - Full command line interface guide
• MCP Server Documentation - External integration details
• Jira Agent Documentation - Natural language Jira operations
• Blender Agent Documentation - 3D content creation
• Features Overview - Complete GAIA capabilities