# MetaGPT Software Company

## Overview

[MetaGPT](https://github.com/geekan/MetaGPT) is a multi-agent AI framework that simulates a **software company** — complete with a Product Manager, Architect, Engineer, and QA Engineer agents — all collaborating to turn a one-sentence idea into a fully functional software project. With 45K+ GitHub stars, MetaGPT is one of the most innovative approaches to AI-driven software development.

Unlike a single coding agent, MetaGPT mirrors real team workflows. When you give it a task like "Build a Snake game in Python", it:

1. **Product Manager** — Writes a Product Requirements Document (PRD)
2. **Architect** — Designs the system architecture and tech stack
3. **Project Manager** — Breaks down tasks and assigns them
4. **Engineers** — Write actual working code for each component
5. **QA Engineer** — Writes unit tests and validates the implementation

The result is a complete project directory with code, documentation, and tests — generated autonomously.

**Key capabilities:**

* **Full software lifecycle** — From requirements to working code in one command
* **Role-based agents** — Specialized agents with distinct responsibilities
* **Document generation** — Auto-produces PRDs, system designs, API specs
* **Multi-language support** — Python, Node.js, Go, and more
* **Data interpreter** — Autonomous data analysis and visualization agent
* **Incremental development** — Add features to existing projects
* **Human interaction mode** — Pause for human review at key stages

**Why Clore.ai for MetaGPT?**

MetaGPT itself is CPU-based, but Clore.ai offers critical advantages:

* **Long-running tasks** — MetaGPT generation can take 10–60 minutes; dedicated servers handle this without timeouts
* **Local LLM backend** — Use Ollama or vLLM to eliminate per-token API costs for large projects
* **Cost control** — At $0.20–0.35/hr, run extensive MetaGPT sessions cheaper than GPT-4o API calls
* **Isolated environment** — Generated code runs in a controlled server environment
* **Team collaboration** — Share a MetaGPT server endpoint across a development team

***

## Requirements

MetaGPT orchestrates LLM API calls — the GPU is needed only if you run a local LLM backend.

| Configuration                      | GPU       | VRAM  | RAM   | Storage | Est. Price      |
| ---------------------------------- | --------- | ----- | ----- | ------- | --------------- |
| **MetaGPT + OpenAI/Anthropic API** | None      | —     | 4 GB  | 20 GB   | \~$0.03–0.08/hr |
| **+ Ollama (Qwen2.5-Coder 7B)**    | RTX 3090  | 24 GB | 16 GB | 40 GB   | \~$0.20/hr      |
| **+ Ollama (DeepSeek Coder 33B)**  | RTX 4090  | 24 GB | 32 GB | 60 GB   | \~$0.35/hr      |
| **+ vLLM (Qwen2.5-Coder 32B)**     | RTX 4090  | 24 GB | 32 GB | 80 GB   | \~$0.35/hr      |
| **+ vLLM (Llama 3.1 70B)**         | A100 80GB | 80 GB | 64 GB | 100 GB  | \~$1.10/hr      |

> **Recommendation:** MetaGPT heavily relies on model quality for coherent multi-step reasoning. For complex projects, use GPT-4o or Claude Sonnet 3.5 APIs, or locally Qwen2.5-Coder-32B / DeepSeek-Coder-V2. See the [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison).

**Software requirements on the Clore.ai server:**

* Docker Engine (pre-installed on all Clore.ai images)
* NVIDIA Container Toolkit (only for local LLM option)
* 20+ GB free disk space (MetaGPT image + generated project files)
* Outbound internet access (for pulling Docker images and reaching LLM APIs)

***

## Quick Start

### Step 1: Connect to Your Clore.ai Server

Book a server on [Clore.ai marketplace](https://clore.ai):

* For API-only: Any server with ≥4 GB RAM
* For local LLM: GPU with ≥24 GB VRAM

```bash
ssh root@<server-ip> -p <ssh-port>
```

### Step 2: Pull the MetaGPT Docker Image

```bash
docker pull metagpt/metagpt:latest
```

> The MetaGPT image is \~3 GB. This may take 2–5 minutes on first pull.

### Step 3: Set Up Configuration

MetaGPT requires a YAML configuration file with your LLM API credentials:

```bash
# Create directories
mkdir -p /opt/metagpt/{config,workspace}

# Extract the default config template from the image
docker run --rm metagpt/metagpt:latest \
  cat /app/metagpt/config/config2.yaml \
  > /opt/metagpt/config/config2.yaml

# View the config
cat /opt/metagpt/config/config2.yaml
```

### Step 4: Configure Your LLM Provider

Edit the configuration file:

```bash
nano /opt/metagpt/config/config2.yaml
```

**For OpenAI (GPT-4o):**

```yaml
llm:
  api_type: "openai"
  model: "gpt-4o"
  base_url: "https://api.openai.com/v1"
  api_key: "sk-your-openai-key-here"

repair_llm_output: true
max_auto_summarize_code: 1
```

**For Anthropic (Claude):**

```yaml
llm:
  api_type: "anthropic"
  model: "claude-3-5-sonnet-20241022"
  api_key: "sk-ant-your-key-here"

repair_llm_output: true
```

**For local Ollama (see GPU section):**

```yaml
llm:
  api_type: "ollama"
  model: "ollama/qwen2.5-coder:32b"
  base_url: "http://host.docker.internal:11434"
  api_key: "ollama"

repair_llm_output: true
```

### Step 5: Run Your First MetaGPT Project

```bash
# Generate a Snake game (classic demo)
docker run --rm --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Create a snake game with Python"
```

Watch the agents work: you'll see PRD generation, system design, code writing, and testing in sequence. Expect 5–15 minutes depending on your LLM.

### Step 6: View the Output

```bash
ls -la /opt/metagpt/workspace/
# You'll see a directory named after your project

find /opt/metagpt/workspace -type f | head -30
# Lists all generated files: .py, .md, requirements.txt, tests/
```

***

## Configuration

### Full Configuration Reference

```yaml
# /opt/metagpt/config/config2.yaml

# Primary LLM configuration
llm:
  api_type: "openai"          # openai | anthropic | ollama | azure | gemini
  model: "gpt-4o"
  base_url: "https://api.openai.com/v1"
  api_key: "your-api-key"
  temperature: 0.0            # Lower = more deterministic code generation
  max_token: 4096

# MetaGPT behavior settings
repair_llm_output: true       # Auto-fix malformed LLM responses
max_auto_summarize_code: 1    # Code summary iterations (0 = disabled)
max_project_auto_run: 5       # Max auto-execution cycles

# Project settings
project_name: ""              # Optional: override generated project name
inc: false                    # Incremental mode (add to existing project)
reqa_file: ""                 # Run QA on a specific file

# Cost tracking
max_budget: 10.0              # Max $ to spend (API calls only)
```

### Running in Interactive Mode

For more control, run MetaGPT with human review checkpoints:

```bash
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Build a REST API for a todo list app with FastAPI" \
  --human-review
```

With `--human-review`, MetaGPT pauses after the PRD and system design stages, allowing you to provide feedback before engineering begins.

### Incremental Development (Add to Existing Project)

```bash
# Continue development on an existing project
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  -v /opt/metagpt/workspace/my-project:/app/metagpt/workspace/my-project \
  metagpt/metagpt:latest \
  metagpt "Add user authentication to the existing todo API" \
  --project-path /app/metagpt/workspace/my-project \
  --inc
```

### Running the Data Interpreter

MetaGPT includes a specialized Data Interpreter agent for data analysis:

```bash
# Interactive Python data analysis
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  -v /path/to/your/data:/data:ro \
  metagpt/metagpt:latest \
  python -m metagpt.roles.di.data_interpreter \
    "Analyze /data/sales.csv and find top-performing products, create visualization"
```

### Docker Compose for Persistent Setup

```yaml
# /opt/metagpt/docker-compose.yml
version: "3.9"

services:
  metagpt:
    image: metagpt/metagpt:latest
    privileged: true
    volumes:
      - /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml:ro
      - /opt/metagpt/workspace:/app/metagpt/workspace
      - /opt/metagpt/logs:/app/metagpt/logs
    environment:
      - PYTHONUNBUFFERED=1
    stdin_open: true
    tty: true
    # Note: MetaGPT is task-based, not a persistent service.
    # Use 'docker compose run metagpt metagpt "your task"' to execute
    entrypoint: ["bash"]
```

```bash
# Run a task via docker-compose
docker compose -f /opt/metagpt/docker-compose.yml \
  run --rm metagpt \
  metagpt "Create a Flask web app with user registration"
```

***

## GPU Acceleration (Local LLM Integration)

### MetaGPT + Ollama

Run MetaGPT completely free (no API costs) using a local coding model:

```bash
# Step 1: Start Ollama with GPU
docker run -d \
  --name ollama \
  --gpus all \
  --restart unless-stopped \
  -p 11434:11434 \
  -v ollama-models:/root/.ollama \
  ollama/ollama:latest

# Step 2: Pull a high-quality coding model
# For RTX 3090/4090 (24 GB VRAM):
docker exec ollama ollama pull qwen2.5-coder:32b      # Best for code
docker exec ollama ollama pull deepseek-coder-v2:16b  # Alternative
# For smaller GPUs (8–16 GB VRAM):
docker exec ollama ollama pull qwen2.5-coder:7b
docker exec ollama ollama pull codellama:13b

# Step 3: Configure MetaGPT for Ollama
cat > /opt/metagpt/config/config2.yaml << 'EOF'
llm:
  api_type: "ollama"
  model: "ollama/qwen2.5-coder:32b"
  base_url: "http://host.docker.internal:11434"
  api_key: "ollama"
  temperature: 0.0
  max_token: 4096

repair_llm_output: true
max_auto_summarize_code: 0
EOF

# Step 4: Run MetaGPT with host network for Ollama access
docker run --rm --privileged \
  --add-host host.docker.internal:host-gateway \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Create a Python CLI tool for file organization"
```

> See the complete [Ollama guide](https://docs.clore.ai/guides/language-models/ollama) for model setup and GPU optimization.

### MetaGPT + vLLM (High Throughput)

For maximum token throughput on large, complex projects:

```bash
# Step 1: Start vLLM with a coding model
docker run -d \
  --name vllm \
  --gpus all \
  --restart unless-stopped \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.90

# Wait for model load
until curl -s http://localhost:8000/health | grep -q ok; do
  echo "Waiting for vLLM..."; sleep 10
done

# Step 2: Configure MetaGPT for vLLM
cat > /opt/metagpt/config/config2.yaml << 'EOF'
llm:
  api_type: "openai"
  model: "Qwen/Qwen2.5-Coder-32B-Instruct"
  base_url: "http://host.docker.internal:8000/v1"
  api_key: "none"
  temperature: 0.0
  max_token: 8192

repair_llm_output: true
EOF

# Step 3: Run MetaGPT
docker run --rm --privileged \
  --add-host host.docker.internal:host-gateway \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Build a complete e-commerce backend with FastAPI and PostgreSQL"
```

> See the [vLLM guide](https://docs.clore.ai/guides/language-models/vllm) for quantization options and multi-GPU setups.

### Recommended Models by Task

| Task Type       | Model                          | Min VRAM | Notes                          |
| --------------- | ------------------------------ | -------- | ------------------------------ |
| Simple scripts  | `qwen2.5-coder:7b`             | 8 GB     | Fast, good for CLI tools       |
| Medium projects | `qwen2.5-coder:14b`            | 12 GB    | Good balance                   |
| Complex systems | `qwen2.5-coder:32b`            | 24 GB    | Best local option              |
| Large codebases | `gpt-4o` / `claude-3-5-sonnet` | API      | Most reliable for complex PRDs |

> **Tip:** Local models work well for code generation but sometimes struggle with complex architectural reasoning. For production-quality PRDs and system designs, consider using GPT-4o or Claude for the planning phase and a local model for code generation.

***

## Tips & Best Practices

### 1. Write Effective Task Prompts

MetaGPT performance heavily depends on your initial prompt quality:

```
✅ Good prompts:
"Create a Python REST API using FastAPI that manages a library catalog.
Features: add/search/delete books, user authentication with JWT, 
SQLite database, OpenAPI docs. Target: production-ready with tests."

"Build a CLI data pipeline tool in Python that reads CSV files,
performs statistical analysis, and outputs charts using matplotlib."

❌ Vague prompts:
"Make a web app"
"Build something with Python"
```

### 2. Estimate API Costs Before Running

```bash
# MetaGPT processes many tokens per project:
# - Simple script: ~50K tokens (~$0.25 with GPT-4o)
# - Medium webapp: ~200K tokens (~$1.00 with GPT-4o)
# - Complex system: ~500K+ tokens (~$2.50+ with GPT-4o)

# Set a budget limit in config:
# max_budget: 2.0  # Stop after $2 spent
```

### 3. Review Generated PRD First

Use `--human-review` for important projects. The PRD stage is where requirements are locked in — catching issues here saves significant token cost compared to revising after code generation.

### 4. Test Generated Code

MetaGPT generates unit tests, but always verify:

```bash
# Navigate to generated project
cd /opt/metagpt/workspace/<your-project>

# Install dependencies
pip install -r requirements.txt

# Run the generated tests
pytest tests/ -v

# Try running the main application
python main.py
```

### 5. Use Version Control

```bash
# Initialize git in the workspace
cd /opt/metagpt/workspace
git init
git add .
git commit -m "Initial MetaGPT generation"

# After each iteration
git add .
git commit -m "MetaGPT: Added authentication feature"
```

### 6. Batch Multiple Projects

Run several projects overnight on Clore.ai for maximum value:

```bash
#!/bin/bash
# /opt/metagpt/batch-run.sh
PROJECTS=(
  "Create a URL shortener service with Python and Redis"
  "Build a Markdown to PDF converter CLI tool"
  "Create a REST API for a blog with comments and tags"
)

for project in "${PROJECTS[@]}"; do
  echo "Starting: $project"
  docker run --rm --privileged \
    -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
    -v /opt/metagpt/workspace:/app/metagpt/workspace \
    metagpt/metagpt:latest \
    metagpt "$project"
  echo "Completed: $project"
done
```

***

## Troubleshooting

### Image Pull Fails

```bash
# If Docker Hub rate limit is hit
docker login  # Log in with your Docker Hub account
docker pull metagpt/metagpt:latest

# Check available disk space
df -h
# MetaGPT image is ~3 GB; workspace can grow to several GB
```

### Config File Not Found

```bash
# Verify the path mapping is correct
docker run --rm \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  metagpt/metagpt:latest \
  ls -la /app/metagpt/config/

# Also verify your YAML is valid
python3 -c "import yaml; yaml.safe_load(open('/opt/metagpt/config/config2.yaml'))"
```

### LLM API Authentication Error

```bash
# Test your API key independently
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

# For Anthropic:
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: sk-ant-your-key" \
  -H "anthropic-version: 2023-06-01"

# Common issues:
# - Key copied with extra whitespace
# - Key expired or quota exceeded
# - Wrong api_type in config (e.g., "openai" vs "anthropic")
```

### Ollama Connection Refused from Container

```bash
# Verify Ollama is running
docker ps | grep ollama
curl http://localhost:11434/api/tags

# Test from MetaGPT container perspective
docker run --rm \
  --add-host host.docker.internal:host-gateway \
  metagpt/metagpt:latest \
  curl http://host.docker.internal:11434/api/tags

# If still failing, check Ollama logs
docker logs ollama --tail 20
```

### Generation Hangs or Times Out

```bash
# Check if the LLM is actually responding
# Add debug logging to see which agent is stuck
docker run --rm --privileged \
  -e PYTHONUNBUFFERED=1 \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Simple task" 2>&1 | tee /opt/metagpt/logs/debug.log

# Common causes:
# - Local model too slow (try smaller quantized model)
# - API rate limiting (add delays or switch tier)
# - Model context window exceeded (reduce max_auto_summarize_code)
```

### Out of Disk Space

```bash
# Generated projects can be large; clean up old ones
du -sh /opt/metagpt/workspace/*
rm -rf /opt/metagpt/workspace/old-project/

# Also clean Docker build cache
docker system prune -f

# Check total usage
df -h /opt/metagpt/
```

### "Repair LLM Output" Loops

```bash
# If MetaGPT keeps retrying due to malformed LLM output:
# 1. Try a more capable model (GPT-4o, Claude Sonnet)
# 2. Reduce temperature (set to 0.0 for determinism)
# 3. Disable repair (if using a capable model):
#    repair_llm_output: false
```

***

## Further Reading

* [MetaGPT GitHub Repository](https://github.com/geekan/MetaGPT) — Source code, examples, roadmap
* [MetaGPT Documentation](https://docs.deepwisdom.ai/main/en/) — Official docs, configuration reference, tutorials
* [MetaGPT Discord](https://discord.gg/DYn29wFk9z) — Community support, use cases, model tips
* [Docker Hub: metagpt/metagpt](https://hub.docker.com/r/metagpt/metagpt) — Available image tags
* [Ollama on Clore.ai](https://docs.clore.ai/guides/language-models/ollama) — Run local LLMs to power MetaGPT for free
* [vLLM on Clore.ai](https://docs.clore.ai/guides/language-models/vllm) — High-throughput local LLM for MetaGPT at scale
* [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison) — Choose the right Clore.ai GPU for your workload
* [SWE-bench Leaderboard](https://www.swebench.com) — Benchmark multi-agent coding frameworks
* [MetaGPT Paper](https://arxiv.org/abs/2308.00352) — Original research: "MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework"