dockai-cli 3.1.8

The Customizable AI Dockerfile Generation Framework

DockAI

AI-Powered Dockerfile Generation Framework

Generate production-ready Dockerfiles from first principles using AI agents

Quick Start • Features • Docs • CI/CD • Contributing

---

🎯 What is DockAI?

DockAI is an agentic AI framework that analyzes your codebase and generates optimized, production-ready Dockerfiles. Unlike template-based tools, DockAI uses first-principles reasoning to understand your application and create Dockerfiles from scratch—handling everything from standard stacks to legacy systems.

# Using pip
pip install dockai-cli

# Or using uv (faster)
uv pip install dockai-cli

dockai build /path/to/project

That's it. DockAI handles the rest.

---

✨ Features

🧠 First-Principles AI No templates. Analyzes file structures, dependencies, and code patterns to deduce the optimal containerization strategy.	🔄 Self-Correcting Workflow Builds and tests Dockerfiles in a sandbox. If something fails, AI reflects, learns, and retries with a new approach.
🛡️ Security-First Built-in Trivy CVE scanning and Hadolint linting. Enforces non-root users, minimal base images, and hardened configs.	🤖 8 Specialized Agents Each agent handles a specific task: analysis, planning, generation, review, and more. All fully customizable.
⚡ Multi-Provider LLMs Supports OpenAI, Azure, Gemini, Anthropic, and Ollama. Mix and match providers per agent (e.g., OpenAI for analysis, Ollama for generation).	🔧 Fully Customizable Override prompts, instructions, and model selection per agent. Use .dockai files for repo-specific configs.
📦 Smart Registry Integration Automatically validates base images against Docker Hub, GCR, Quay, and GHCR. Prioritizes small, secure variants like alpine and slim.	📊 Full Observability Built-in OpenTelemetry tracing and LangSmith support for distributed observability and LLM debugging. Export traces to console, OTLP backends, or LangSmith.

---

🚀 Three Ways to Use DockAI

DockAI is designed to fit into any workflow, whether you are a developer, a DevOps engineer, or an AI user.

1. The CLI (For Developers)

Perfect for running locally on your machine.

# Install (choose one)
pip install dockai-cli    # Using pip
uv pip install dockai-cli # Using uv (faster)

# Run
dockai build .

2. GitHub Actions (For CI/CD)

Automate Dockerfile generation in your pipelines.

steps:
  - uses: actions/checkout@v3
  - uses: itzzjb/dockai@v3
    with:
      openai_api_key: ${{ secrets.OPENAI_API_KEY }}

3. MCP Server (For AI Agents)

Use DockAI directly inside Claude Desktop, Cursor, or any MCP-compliant tool.

1. Install dockai-cli.
2. Configure your MCP client:

{
  "mcpServers": {
    "dockai": {
      "command": "python",
      "args": ["-m", "dockai.core.mcp_server"]
    }
  }
}

3. Ask your AI: "Analyze this project and generate a Dockerfile for it."

---

Configuration

Create a .env file:

# Required: Choose your LLM provider and add the API key
OPENAI_API_KEY=sk-your-api-key

# Optional: Use a different provider (openai, azure, gemini, anthropic, ollama)
# DOCKAI_LLM_PROVIDER=openai

Usage

# Generate Dockerfile for your project
dockai build /path/to/project

# With verbose output
dockai build /path/to/project --verbose

---

🏗️ How It Works

flowchart TB
    subgraph Discovery["📊 Discovery Phase"]
        scan["📂 scan_node<br/>Scan directory tree"]
        analyze["🧠 analyze_node<br/>AI: Detect stack & requirements"]
        read["📖 read_files_node<br/>Read critical files"]
    end
    
    subgraph Blueprint["🏗️ Blueprint Phase"]
        blueprint["📝 blueprint_node<br/>AI: Architect build plan & runtime config"]
    end
    
    subgraph Generation["⚙️ Generation Phase"]
        generate["⚙️ generate_node<br/>AI: Write Dockerfile"]
    end
    
    subgraph Validation["✅ Validation Phase"]
        review["🔒 review_node<br/>AI: Security audit"]
        validate["✅ validate_node<br/>Build, test & scan"]
    end
    
    subgraph Feedback["🔄 Self-Correction Loop"]
        reflect["🤔 reflect_node<br/>AI: Analyze failure"]
        increment["🔄 increment_retry<br/>Update retry count"]
    end
    
    Start([▶ Start]) --> scan
    scan --> analyze --> read --> blueprint
    blueprint --> generate --> review
    
    review -->|"check_security: pass"| validate
    review -->|"check_security: fail"| reflect
    
    validate -->|"should_retry: end"| End([🏁 Done])
    validate -->|"should_retry: reflect"| reflect
    
    reflect --> increment
    increment -->|"check_reanalysis: generate"| generate
    increment -->|"check_reanalysis: blueprint"| blueprint
    increment -->|"check_reanalysis: analyze"| analyze

---

🤖 The 8 AI Agents

Agent	Role	Model Type
Analyzer	Project discovery & stack detection	Fast
Architect (Blueprint)	Strategic build planning & runtime config	Powerful
Generator	Dockerfile creation	Powerful
Generator (Iterative)	Debugging failed Dockerfiles	Powerful
Reviewer	Security audit & hardening	Fast
Reflector	Failure analysis & learning	Powerful
Error Analyzer	Error classification	Fast
Iterative Improver	Targeted fix application	Powerful

---

⚙️ Configuration

Environment Variables

LLM Provider Configuration

Variable	Description	Default
DOCKAI_LLM_PROVIDER	Provider (openai, azure, gemini, anthropic, ollama)	openai
OPENAI_API_KEY	OpenAI API key	Required*
GOOGLE_API_KEY	Google Gemini API key	Required*
ANTHROPIC_API_KEY	Anthropic Claude API key	Required*
AZURE_OPENAI_API_KEY	Azure OpenAI API key	Required*
AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL	-
AZURE_OPENAI_API_VERSION	Azure OpenAI API version	2024-02-15-preview
OLLAMA_BASE_URL	Ollama base URL	http://localhost:11434

*Only one API key required for your chosen provider.

Per-Agent Model Configuration

Variable	Description	Default
DOCKAI_MODEL_ANALYZER	Model for project analyzer	gpt-4o-mini
DOCKAI_MODEL_BLUEPRINT	Model for build architect (blueprint)	gpt-4o
DOCKAI_MODEL_GENERATOR	Model for Dockerfile generator	gpt-4o
DOCKAI_MODEL_GENERATOR_ITERATIVE	Model for iterative generator	gpt-4o
DOCKAI_MODEL_REVIEWER	Model for security reviewer	gpt-4o-mini
DOCKAI_MODEL_REFLECTOR	Model for failure reflector	gpt-4o
DOCKAI_MODEL_ERROR_ANALYZER	Model for error analyzer	gpt-4o-mini
DOCKAI_MODEL_ITERATIVE_IMPROVER	Model for iterative improver	gpt-4o

Tip: Mix providers by prefixing with provider/, e.g., DOCKAI_MODEL_ANALYZER=openai/gpt-4o-mini

Generation Settings

Variable	Description	Default
MAX_RETRIES	Maximum retry attempts if Dockerfile validation fails	3

Validation Settings

Variable	Description	Default
DOCKAI_VALIDATION_MEMORY	Memory limit for container sandbox	512m
DOCKAI_VALIDATION_CPUS	CPU limit for container validation	1.0
DOCKAI_VALIDATION_PIDS	Maximum processes for validation	100
DOCKAI_MAX_IMAGE_SIZE_MB	Maximum image size in MB (0 to disable)	500
DOCKAI_SKIP_HEALTH_CHECK	Skip health check during validation	false

File Analysis Settings

Variable	Description	Default
DOCKAI_TRUNCATION_ENABLED	Enable smart truncation of large files	false
DOCKAI_TOKEN_LIMIT	Token limit for auto-truncation	100000
DOCKAI_MAX_FILE_CHARS	Max chars per file (when truncating)	200000
DOCKAI_MAX_FILE_LINES	Max lines per file (when truncating)	5000

Security Settings

Variable	Description	Default
DOCKAI_SKIP_HADOLINT	Skip Hadolint Dockerfile linting	false
DOCKAI_SKIP_SECURITY_SCAN	Skip Trivy security scan	false
DOCKAI_SKIP_SECURITY_REVIEW	Skip AI security review (auto for scripts)	false
DOCKAI_STRICT_SECURITY	Fail on ANY HIGH/CRITICAL vulnerabilities	false

Efficiency Settings

Variable	Description	Default
DOCKAI_LLM_CACHING	Enable in-memory LLM response caching	true

Observability & Tracing

Variable	Description	Default
DOCKAI_ENABLE_TRACING	Enable OpenTelemetry tracing	false
DOCKAI_TRACING_EXPORTER	Tracing exporter (console, otlp)	console
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP endpoint URL (for Jaeger/Tempo/Datadog)	http://localhost:4317
OTEL_SERVICE_NAME	Service name for traces	dockai
LANGCHAIN_TRACING_V2	Enable LangSmith tracing	false
LANGCHAIN_API_KEY	LangSmith API Key	-
LANGCHAIN_PROJECT	LangSmith Project Name	dockai

Custom Instructions (Per-Agent)

Variable	Description
DOCKAI_ANALYZER_INSTRUCTIONS	Appended to analyzer prompt
DOCKAI_BLUEPRINT_INSTRUCTIONS	Appended to blueprint prompt
DOCKAI_GENERATOR_INSTRUCTIONS	Appended to generator prompt
DOCKAI_GENERATOR_ITERATIVE_INSTRUCTIONS	Appended to iterative generator prompt
DOCKAI_REVIEWER_INSTRUCTIONS	Appended to reviewer prompt
DOCKAI_REFLECTOR_INSTRUCTIONS	Appended to reflector prompt
DOCKAI_ERROR_ANALYZER_INSTRUCTIONS	Appended to error analyzer prompt
DOCKAI_ITERATIVE_IMPROVER_INSTRUCTIONS	Appended to iterative improver prompt

Custom Prompts (Advanced)

Variable	Description
DOCKAI_PROMPT_ANALYZER	Completely replaces analyzer prompt
DOCKAI_PROMPT_BLUEPRINT	Completely replaces blueprint prompt
DOCKAI_PROMPT_GENERATOR	Completely replaces generator prompt
DOCKAI_PROMPT_GENERATOR_ITERATIVE	Completely replaces iterative generator prompt
DOCKAI_PROMPT_REVIEWER	Completely replaces reviewer prompt
DOCKAI_PROMPT_REFLECTOR	Completely replaces reflector prompt
DOCKAI_PROMPT_ERROR_ANALYZER	Completely replaces error analyzer prompt
DOCKAI_PROMPT_ITERATIVE_IMPROVER	Completely replaces iterative improver prompt

Note: Instructions are appended to defaults; prompts completely replace them. Use .dockai file for repo-specific configs.

Repository-Level Configuration

Create a .dockai file in your project root:

[instructions_analyzer]
This is a Django application with Celery workers.

[instructions_generator]
Use gunicorn as the WSGI server.
Run database migrations at container start.

[instructions_reviewer]
All containers must run as non-root (UID >= 10000).

---

🔗 GitHub Actions

name: Auto-Dockerize

on:
  push:
    branches: [main]

jobs:
  dockai:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: itzzjb/dockai@v3
        with:
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}

💡 Tip: By default, the Dockerfile is generated at runtime and not committed. If you want to save it to your repository, see the Committing Generated Dockerfile guide.

Multi-Provider Example

- uses: itzzjb/dockai@v3
  with:
    llm_provider: gemini
    google_api_key: ${{ secrets.GOOGLE_API_KEY }}
    max_retries: 5
    strict_security: true

Mixed Provider Example

Use Ollama locally for most tasks, but OpenAI for complex analysis:

# .env
DOCKAI_LLM_PROVIDER=ollama
DOCKAI_MODEL_ANALYZER=openai/gpt-4o-mini

See GitHub Actions Guide for all options.

---

📖 Documentation

Document	Description
Getting Started	Installation, configuration, first run
Architecture	Deep dive into the internal design
Configuration	Full reference for env vars and inputs
Customization	Tuning agents for your organization
API Reference	Module and function documentation
GitHub Actions	CI/CD integration guide
MCP Server	AI Agent integration guide
FAQ	Frequently asked questions

💡 MCP Support: Expose DockAI as a Model Context Protocol server for use in any MCP client.

---

🛠️ Tech Stack

Technology	Purpose
Python 3.10+	Core runtime
LangGraph	Stateful agent workflow orchestration
LangChain	LLM provider integration
Pydantic	Structured output validation
Rich + Typer	Beautiful CLI interface
Trivy	Security vulnerability scanning
Hadolint	Dockerfile linting and best practices
OpenTelemetry	Distributed tracing and observability

---

🤝 Contributing

Contributions are welcome! Feel free to open issues and pull requests.

---

📄 License

MIT License - see LICENSE for details.

---

_{Built with ❤️ by Januda Bethmin}