Quick Start

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Run on any project
uvx wunderunner /path/to/your/project

That's it. wunderunner analyzes your project and generates Docker configs.

How It Works

flowchart TD
    Analyze[🔍 Analyze Project] --> secrets{Secrets?}
    secrets -->|yes| CollectSecrets[🔐 Collect Secrets]
    secrets -->|no| Dockerfile
    CollectSecrets --> Dockerfile

    Dockerfile[📄 Generate Dockerfile] --> Validate[✅ Validate]
    Validate -->|pass| Services[🐳 Generate Compose]
    Validate -->|fail| RetryOrHint
    Services -->|success| Build[🔨 Build Image]
    Services -->|fail| RetryOrHint
    Build -->|success| Start[🚀 Start Containers]
    Build -->|fail| RetryOrHint
    Start -->|success| Healthcheck[💓 Healthcheck]
    Start -->|fail| RetryOrHint
    Healthcheck -->|healthy| Success((✨ Success))
    Healthcheck -->|fail| RetryOrHint

    RetryOrHint{Retry?} -->|validation/generation error| Dockerfile
    RetryOrHint -->|runtime error| ImproveDockerfile[🔧 Improve Dockerfile]
    RetryOrHint -->|exhausted| HumanHint[💬 Ask Human]

    ImproveDockerfile -->|fixed| Validate
    ImproveDockerfile -->|compose modified| Build
    ImproveDockerfile -->|low confidence| HumanHint

    HumanHint --> Dockerfile

The loop continues until success. Each failure feeds back as a learning, informing the next generation attempt with specific context about what went wrong and how to fix it.

Features

Key Concepts

Human in the Loop

When automatic retries are exhausted, wunderunner asks for help instead of giving up. You provide a hint, maybe the project needs a specific system dependency, or uses an unconventional setup. Your hint becomes part of the context for the next attempt.

❌ Build failed after 3 attempts
💬 What should I know about this project?
> This uses puppeteer and needs chromium installed

✓ Got it. Retrying with that context...

Learnings & Context

Every failure teaches the system something. Learnings accumulate across retry cycles:

• Phase: Where it failed (build, start, healthcheck)
• Error type: What kind of failure occurred
• Error message: The actual error output
• Context: Additional info (previous fixes tried, human hints)

The Dockerfile generator receives all learnings, allowing it to avoid repeating mistakes and build on what worked.

Caching

Analysis results are cached in .wunderunner/ to avoid re-scanning unchanged projects:

wxr /path/to/project           # Uses cache if available
wxr /path/to/project --rebuild # Ignores cache, fresh analysis

Cached artifacts:

• Project structure analysis
• Detected runtime and framework
• Environment variables and secrets
• Generated Dockerfile and docker-compose.yaml

Runtime Healing

Failures during build, start, or healthcheck trigger the ImproveDockerfile agent. This unified agent can:

• Modify the Dockerfile (add missing packages, fix commands)
• Modify project files (remove problematic configs like .babelrc)
• Update docker-compose.yaml (fix port mappings, remove bad volumes)
• Add .dockerignore entries to exclude conflicting files

The agent reads error messages carefully and applies targeted fixes. If it modifies docker-compose.yaml, it skips regeneration and goes directly to build.

License: MIT | Python: 3.11+ | CLI: wxr