Docker Agent - GAIA SDK

Source Code: hub/agents/docker/python/gaia_agent_docker/agent.py · src/gaia/apps/docker/app.py

Overview

The GAIA Docker Agent provides a natural language interface for containerizing applications. The agent analyzes your application structure, generates appropriate Dockerfiles, and provides guidance for building and running containers - all through conversational commands. No Docker expertise required.

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

Quick Start

Prerequisites

Docker Installation (Required): Docker Engine or Desktop: Download from docker.com
GAIA Installation: Follow the Setup guide, then install with MCP extras:
uv pip install "amd-gaia[mcp]"
Download Required Model: The Docker agent uses the Gemma-4-E4B-it-GGUF model for reliable Dockerfile generation and application analysis. Use the Lemonade server’s model manager to download it:
1. Start Lemonade server at the GPU/CPU profile context size: lemonade-server serve --ctx-size 65536
2. Open the model manager in your browser (typically http://localhost:13305)
3. Search for and download: Gemma-4-E4B-it-GGUF
Note: The download is about 5.6 GB (a 4.6 GB Q4_K_M weights file plus a 0.9 GB vision projector). It provides excellent results for Dockerfile generation and application analysis. Important: GAIA pins one context window per device profile — 65536 on GPU/CPU, 32768 on NPU — so every agent shares a single resident (model, ctx_size) pair and switching agents never forces a reload. Starting Lemonade below the profile size makes GAIA reload the model at the larger window on first use. For more details on Lemonade Server CLI options, see the Lemonade Server documentation.

Verify Installation

Check Docker is installed:

docker --version

Check that GAIA is installed correctly:

gaia --version

Test Docker agent with a Flask application:

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

Basic Usage

Generate Dockerfile for your application:

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

Create Dockerfile, build, and run the container:

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

Architecture Overview

Key Components

DockerAgent (hub/agents/docker/python/gaia_agent_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, save_dockerfile, build_image, run_container
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
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

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

Usage Examples

Natural Language Commands

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

gaia docker "create a Dockerfile for my application" -d "C:\Users\user\src\test\netscan"

gaia docker "containerize this Flask app with gunicorn" -d ./flask-app

gaia docker "create a Dockerfile for my application and then build and run the container" -d "C:\Users\user\src\test\netscan"

gaia docker "create Dockerfile with Python 3.11" -d ./project

The command parameter accepts natural language instructions. The agent can:

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

Use GAIA Docker directly within GitHub Copilot for seamless containerization assistance in your IDE.

Prerequisites

Start Lemonade Server with Extended Context:
lemonade-server serve --ctx-size 65536
Note: The extended context size is required for handling complex Docker queries through Copilot.
Start GAIA MCP Bridge:
gaia mcp start --port 8080

Configure VSCode MCP Settings: Add to your VSCode mcp.json (typically in .vscode/mcp.json):

{
    "servers": {
        "gaia-docker": {
            "url": "http://localhost:8080/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

Restart VSCode to load the MCP configuration

Usage with Copilot

Once configured, you can reference GAIA Docker in your Copilot prompts using #gaia-docker:

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

Copilot will communicate with the GAIA Docker agent through MCP, analyzing your project and generating appropriate Dockerfile configurations. The agent has full context of your application structure and can provide intelligent recommendations.

Workflow

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

For more details on the MCP bridge, see MCP Documentation.

Integration Methods

1. Python API (Direct Integration)

from gaia_agent_docker.agent import DockerAgent

# Initialize and execute
agent = DockerAgent(model_id="Gemma-4-E4B-it-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’s MCP support is powered by FastMCP from the Model Context Protocol Python SDK. The server uses FastMCP’s “streamable-http” transport, providing both HTTP POST and SSE streaming at the /mcp endpoint. Start the Docker MCP Server:

gaia mcp docker --port 8080

The server supports JSON-RPC interface and works with GitHub Copilot, Claude Desktop, and other MCP clients. Current MCP Limitations:

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

JSON-RPC Request Format:

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

Works with any HTTP client (JavaScript/fetch, Python/requests, cURL, etc.). For detailed MCP integration examples, see:

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

Key Features

Automatic Application Analysis

The agent automatically detects:

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

The agent generates Dockerfiles that include:

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

The agent orchestrates a complete containerization workflow:

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

Next Steps Guidance

After Dockerfile generation, the agent provides:

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]

The command is a natural language instruction that tells the agent what Docker operations to perform (e.g., “create a Dockerfile”, “build and run my app”).

Available Options

Option	Type	Default	Description
`command`	string	Required	Natural language instruction (positional argument). Can request Dockerfile creation, building, running, or all three.
`-d`, `--directory`	string	`.`	Directory containing the application to containerize
`-v`, `--verbose`	flag	-	Enable verbose output
`--debug`	flag	-	Enable debug logging
`--model`	string	`Gemma-4-E4B-it-GGUF`	LLM model to use

Troubleshooting

Common Issues and Solutions

”Docker Not Installed”

Check Docker installation:

docker --version

If not installed, download from docker.com.

”Lemonade Server Not Running”

Start the Lemonade server:

lemonade-server serve

Verify it’s running:

curl http://localhost:13305/health

“No Dockerfile Generated”

If the agent doesn’t generate a Dockerfile:

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

”Model Not Found”

Verify the Gemma 4 E4B model is downloaded:

Open Lemonade UI: http://localhost:13305
Check Models section for Gemma-4-E4B-it-GGUF

MCP Integration Issues

Check if MCP bridge is running:

gaia mcp status

Restart the bridge if needed:

gaia mcp stop

gaia mcp start

Debug Mode

For detailed troubleshooting, check the agent logs. Logs are written to gaia.log:

tail -f gaia.log

MCP logs (if using MCP bridge):

tail -f gaia.mcp.log

Best Practices

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

Limitations

Current limitations of the Docker agent:

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

Quick Python Test:

from gaia_agent_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")

MCP Test:

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

​Overview

​Quick Start

​Prerequisites

​Verify Installation

​Basic Usage

​Architecture Overview

​Key Components

​How It Works

​Usage Examples

​Natural Language Commands

​GitHub Copilot Integration

​Prerequisites

​Usage with Copilot

​Workflow

​Integration Methods

​1. Python API (Direct Integration)

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

​Key Features

​Automatic Application Analysis

​Intelligent Dockerfile Generation

​Multi-Step Workflow

​Next Steps Guidance

​Command Reference

​Basic Command Structure

​Available Options

​Troubleshooting

​Common Issues and Solutions

​”Docker Not Installed”

​”Lemonade Server Not Running”

​“No Dockerfile Generated”

​”Model Not Found”

​MCP Integration Issues

​Debug Mode

​Best Practices

​Limitations

​Testing Your Integration

​See Also

Overview

Quick Start

Prerequisites

Verify Installation

Basic Usage

Architecture Overview

Key Components

How It Works

Usage Examples

Natural Language Commands

GitHub Copilot Integration

Prerequisites

Usage with Copilot

Workflow

Integration Methods

1. Python API (Direct Integration)

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

Key Features

Automatic Application Analysis

Intelligent Dockerfile Generation

Multi-Step Workflow

Next Steps Guidance

Command Reference

Basic Command Structure

Available Options

Troubleshooting

Common Issues and Solutions

”Docker Not Installed”

”Lemonade Server Not Running”

“No Dockerfile Generated”

”Model Not Found”

MCP Integration Issues

Debug Mode

Best Practices

Limitations

Testing Your Integration

See Also