# 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](/guides/getting-started/gpu-comparison.md).

**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](/guides/language-models/ollama.md) 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](/guides/language-models/vllm.md) 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](/guides/language-models/ollama.md) — Run local LLMs to power MetaGPT for free
* [vLLM on Clore.ai](/guides/language-models/vllm.md) — High-throughput local LLM for MetaGPT at scale
* [GPU Comparison Guide](/guides/getting-started/gpu-comparison.md) — 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"


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/ai-platforms-and-agents/metagpt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.