Installation

Installation#

Prerequisites#

MassGen requires Python 3.11 or higher. You can check your Python version with:

python --version

If you need to install or upgrade Python, visit python.org/downloads.

Quick Start Installation#

Getting Started - Complete First-Run Flow#

Quickstart Setup (Fastest way to get running):

# Step 1: Set up API keys, Docker, and skills
uv run massgen --setup

# Step 2: Create a simple config and start
uv run massgen --quickstart

What ``–setup`` does:

  • Configures your API keys (OpenAI, Anthropic, Google, xAI)

  • Offers to set up Docker images for code execution

  • Offers to install skills (openskills, Anthropic collection)

What ``–quickstart`` does:

  • Asks how many agents you want (1-5, default 3)

  • Asks which backend/model for each agent (or same for all)

  • Auto-detects Docker availability and configures execution mode

  • Creates a ready-to-use config and launches into interactive mode

After first-run setup:

# Start conversation with your default config
massgen

# Or run a single query
massgen "Your question here"

Tip

The entire flow takes 1-2 minutes. You’ll be in an interactive conversation with your agents immediately after setup!

Alternative: Full Setup Wizard

For more control over configuration, use the full wizard:

massgen --init

This guides you through:

  1. Choose Your Configuration

    • 📦 Browse ready-to-use configs/examples - Select from 100+ pre-built configurations

    • Build from template - Create custom agents with guided setup (Simple Q&A, Research & Analysis, Code & Files, etc.)

  2. Save as Default (optional)

    • When browsing existing configs or examples, you’ll be asked: “Save this as your default config?”

    • Choose Yes to use it automatically on future massgen runs

    • Choose No to try it once without saving

  3. Start Chatting Immediately

    • After selection, you’re launched directly into interactive mode

    • Multi-turn conversation with your chosen configuration

Supported API Key Providers#

Main backends:

  • OpenAI, Anthropic (Claude), Google Gemini, xAI (Grok)

  • Azure OpenAI

ChatCompletion providers:

  • Cerebras AI, Together AI, Fireworks AI, Groq, Nebius AI Studio, OpenRouter

  • ZAI (Zhipu.ai), Kimi/Moonshot AI, POE, Qwen (Alibaba)

Note

You can skip all providers if you’re using local models (vLLM, Ollama, etc.) which don’t require API keys.

Manual API Key Setup (Optional)#

If you prefer to set up API keys manually before running MassGen:

# Unix/Mac: Create the .env file
mkdir -p ~/.config/massgen
vim ~/.config/massgen/.env

# Windows: Create the .env file
mkdir %USERPROFILE%\.config\massgen
notepad %USERPROFILE%\.config\massgen\.env

# Add your API keys (same format for all platforms)
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key
GEMINI_API_KEY=your-gemini-key
XAI_API_KEY=xai-your-key

Complete API Key Reference:

# Main backends
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
XAI_API_KEY=xai-...

# Azure
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=...

# ChatCompletion providers
CEREBRAS_API_KEY=...
TOGETHER_API_KEY=...
FIREWORKS_API_KEY=...
GROQ_API_KEY=...
NEBIUS_API_KEY=...
OPENROUTER_API_KEY=...
ZAI_API_KEY=...
MOONSHOT_API_KEY=...        # Also accepts KIMI_API_KEY
POE_API_KEY=...
QWEN_API_KEY=...

MassGen API Key Lookup Order#

MassGen looks for API keys in this order:

  1. Environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

  2. ~/.config/massgen/.env (user config - recommended)

  3. Project-specific .env file in current directory (highest priority)

Reconfiguring API Keys#

You can re-run the API key wizard anytime:

# Launch API key setup
massgen --setup

First-Run Setup Flow Walkthrough#

When you run massgen for the first time, here’s what you’ll see:

  ╔══════════════════════════════════════════════════════════╗
  ║             👋  Welcome to MassGen!                      ║
  ╚══════════════════════════════════════════════════════════╝

  ✅ API keys detected

  Let's set up your default configuration...

  Step 1 of 4: Select Your Use Case

  Browse ready-to-use configs, or pick a template to build your own.

» 📦  Browse ready-to-use configs / examples

  ─ or build from template ─

  ⚙️  Custom Configuration           [Choose your own tools]
  💬  Simple Q&A                     [Basic chat (no special tools)]
  🔍  Research & Analysis            [Web search enabled]
  💻  Code & Files                   [File ops + code execution]
  🐳  Code & Files (Docker)          [File ops + isolated Docker execution]
  📊  Data Analysis                  [Files + code + image analysis]
  🎨  Multimodal Analysis            [Images, audio, video understanding]

Option 1: Browse Ready-to-Use Configs (Fastest)

Select this to browse 100+ pre-built configurations organized by category:

📦  Browse ready-to-use configs / examples

┌─────────────────────────────────────────────────────────┐
│ 👤 Your Configs                    1                    │
│ 📂 Project Configs                 0                    │
│ 📂 Current Directory               2                    │
│ 📦 Package Examples                107                  │
└─────────────────────────────────────────────────────────┘

Select a configuration:
» three_agents_default.yaml  (3 agents, diverse perspectives)
  research_team.yaml          (Web search + analysis)
  coding_assistant.yaml       (File ops + code execution)

After selecting, you’ll be asked:

📦 You selected a package example
   /path/to/massgen/configs/basic/multi/three_agents_default.yaml

Save this as your default config? [y/N]:

  • Choose y to save and use automatically on future runs

  • Choose n to try it once without saving

Then immediately launches into interactive mode! 🚀

Option 2: Build from Template (Customized)

Select a template to create a custom configuration with guided setup:

🔍  Research & Analysis            [Web search enabled]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 2 of 4: Agent Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Available providers:
• ✅ OpenAI - gpt-5, gpt-5-mini, gpt-5-nano...
• ✅ Claude - claude-sonnet-4, claude-opus-4...
• ✅ Gemini - gemini-2.5-flash, gemini-2.5-pro...

How many agents? 3 agents (recommended)
Select provider: OpenAI
Select models: gpt-5-mini, gpt-5-mini, gpt-5-mini

✅ Configuration saved to: ~/.config/massgen/config.yaml

🚀 Launching interactive mode...

Your configuration is saved to ~/.config/massgen/config.yaml and will be used for all future runs.

Available Build Templates#

The wizard offers several preset configurations that auto-configure tools and capabilities for common use cases:

Custom Configuration

Full flexibility to choose any combination of agents, models, and tools. You’ll configure everything manually. * Choose your own tools * Use for: Specialized workflows with specific requirements

Simple Q&A

Basic question answering with multiple perspectives. No special tools configured. * Multiple agents provide diverse perspectives and cross-verification * Use for: General questions, discussions, brainstorming

Research & Analysis (Auto-configured)

  • ✓ Web Search: Real-time internet search for current information, fact-checking, and source verification

  • ✓ Multi-Agent Collaboration: 3 agents recommended for diverse perspectives and cross-verification

  • Available for: OpenAI, Claude, Gemini, Grok

  • Use for: Research queries, current events, fact-checking, comparative analysis

Code & Files (Auto-configured)

  • ✓ Filesystem Access: File read/write operations in isolated workspace

  • ✓ Code Execution: OpenAI Code Interpreter or Claude/Gemini native code execution

  • Claude Code recommended for best filesystem support

  • Use for: Code generation, refactoring, testing, file operations

Code & Files (Docker) (Auto-configured)

  • ✓ Filesystem Access: File read/write operations

  • ✓ Code Execution: Backend-native code execution

  • ✓ Docker Isolation: Fully isolated container execution via MCP, persistent packages, network controls

  • ⚠️ Setup Required: Docker Engine 28.0.0+, docker Python library, and massgen-executor image (see massgen/docker/README.md)

  • Use for: Secure code execution with full isolation and persistent dependencies

Data Analysis (Auto-configured)

  • ✓ Filesystem Access: Read/write data files (CSV, JSON, etc.), save visualizations

  • ✓ Code Execution: Data processing, transformation, statistical analysis, visualization generation

  • ✓ Image Understanding: Analyze charts, graphs, and visualizations; extract data from images

  • Available for: OpenAI, Claude Code, Gemini, Azure OpenAI

  • Use for: Data analysis, chart interpretation, statistical processing, visualization

Multimodal Analysis (Auto-configured)

  • ✓ Image Understanding: Analyze images, screenshots, charts; OCR and text extraction * Available for: OpenAI, Claude Code, Gemini, Azure OpenAI

  • ✓ Audio Understanding: Transcribe and analyze audio (where supported) * Available for: Claude, ChatCompletion

  • ✓ Video Understanding: Analyze video content (where supported) * Available for: Claude, ChatCompletion, OpenAI

  • Note: Different backends support different modalities

  • Use for: Image analysis, screenshot interpretation, multimedia content analysis

Note

Presets marked (Auto-configured) automatically enable specific tools and capabilities during setup. You can still customize further if needed.

Quick Usage Examples#

After setup, using MassGen is simple:

# Use your default configuration
massgen "What is quantum computing?"

# Override with a specific model for this query
massgen --model gpt-5-mini "Quick question"

# Use a pre-built example configuration
massgen --config @examples/basic/multi/three_agents_default "Compare renewable energy sources"

# Start interactive multi-turn mode
massgen

Example Configurations#

MassGen ships with ready-to-use example configurations:

# List all available examples
massgen --list-examples

# Use an example configuration
massgen --config @examples/basic/single/single_gpt5nano "Your question"
massgen --config @examples/research_team "Research query"

# Copy an example to customize
massgen --example basic_multi > my-config.yaml

See Configuration for more details on customizing configurations.

Method 2: Development Installation (For Developers)#

If you want to contribute to MassGen or customize the source code:

# Clone the repository
git clone https://github.com/Leezekun/MassGen.git
cd MassGen

# Install in editable mode
pip install -e .

# Or with uv (faster)
pip install uv
uv pip install -e .

Automated Development Setup (Unix/Linux/macOS)

For a complete development environment setup including dependencies, skills, and Docker images:

# Full automated setup
./scripts/init.sh

# Or just install skills (Anthropic + Crawl4AI)
./scripts/init_skills.sh

The init.sh script will:

  • ✓ Check system requirements (Python 3.11+, Node.js, Docker)

  • ✓ Install uv package manager

  • ✓ Install Python dependencies (uv sync)

  • ✓ Install npm global packages (openskills, semtools, Claude Code CLI, Gemini CLI)

  • ✓ Install skills (Anthropic collection + Crawl4AI)

  • ✓ Build Docker runtime images (standard + sudo variants)

  • ✓ Setup .env file from template

  • ✓ Verify installation

Script Options:

# Skip Docker builds (saves time)
./scripts/init.sh --skip-docker

# Skip skills installation
./scripts/init.sh --skip-skills

# Skip npm package installation
./scripts/init.sh --skip-npm

# Show help
./scripts/init.sh --help

Note

Windows Support: Windows support for init scripts is planned for a future release. Windows users should follow the manual installation steps for each component listed above.

Development installation gives you:

  • 🔄 Live changes: Edits are immediately reflected

  • 🛠️ Full source access: Modify any part of MassGen

  • 📦 All features: Same as pip install, but with source code

Using uv tool for Multi-Turn Sessions

For the best experience with multi-turn conversations and working across different project directories, install MassGen as a uv tool:

# Install as a global uv tool (from MassGen directory)
cd MassGen
uv tool install -e .

# Now you can use massgen from anywhere
cd ~/your-project
massgen  # Start interactive multi-turn session

# Sessions are saved to .massgen/sessions/ in your current directory
# Context is preserved across turns automatically

Benefits of uv tool for multi-turn:

  • 🌍 Global Access: Run massgen from any directory

  • 💬 Session Isolation: Each project gets its own .massgen/sessions/ directory

  • 📁 Clean Workspaces: Sessions and workspaces stay organized per-project

  • 🔄 Live Updates: Changes to MassGen source are immediately available (editable mode)

See Interactive Multi-Turn Mode for complete multi-turn conversation documentation.

Using MassGen After Installation#

After installing via either method, you can use MassGen in several ways:

Command Line Interface#

# Single query with default config
massgen "Your question"

# Interactive multi-turn mode
massgen

# Quick single-agent mode
massgen --model gemini-2.5-flash "Quick question"

# Use example configuration
massgen --config @examples/basic/multi/three_agents_default "Complex question"

# Use custom configuration file
massgen --config ./my-agents.yaml "Your question"

Python API#

MassGen provides a simple async Python API:

import asyncio
import massgen

# Quick single-agent query
result = await massgen.run(
    query="What is machine learning?",
    model="gpt-5-mini"
)
print(result['final_answer'])

# Multi-agent with configuration
result = await massgen.run(
    query="Analyze climate change trends",
    config="@examples/research_team"
)

# Or from sync code
result = asyncio.run(
    massgen.run("Question", model="gemini-2.5-flash")
)

See Python API for complete API documentation.

Configuration Management#

Configuration Files Location#

MassGen uses the following directory structure:

~/.config/massgen/                        # Windows: %USERPROFILE%\.config\massgen\
├── config.yaml              # Your default configuration (from wizard)
├── agents/                  # Your custom named configurations
│   ├── research-team.yaml
│   └── coding-agents.yaml
└── .env                     # API keys (optional)

The config.yaml file is created by the setup wizard and used by default when you run massgen without specifying a config.

Reconfiguring MassGen#

You can re-run the setup wizard anytime:

# Launch configuration wizard
massgen --init

# This will:
# - Let you create a new default config (overwrites existing)
# - Or save as a named config in ~/.config/massgen/agents/ (Windows: %USERPROFILE%\.config\massgen\agents\)

Understanding the .massgen Directory#

MassGen organizes all its working files in a .massgen/ directory within your project. This keeps your project clean and makes it easy to exclude MassGen files from version control by adding .massgen/ to your .gitignore.

What’s inside?

  • sessions/ - Multi-turn conversation history

  • workspaces/ - Agent working directories for file operations

  • snapshots/ - Workspace snapshots shared between agents

  • temp_workspaces/ - Previous turn results for context

When is it created?

The .massgen/ directory is automatically created when you use multi-turn mode, file operations, or workspace features. Simple single-agent queries don’t create it.

See also

For a complete explanation of workspace management and directory structure, see Core Concepts (State Management & .massgen Directory section)

Optional Dependencies#

AG2 Framework Integration#

If you want to use AG2 agents alongside native MassGen agents:

pip install massgen[external]

This is only required if you plan to use AG2 configuration files.

Docker Image Setup#

MassGen uses Docker containers for secure code execution. The Docker images provide a sandboxed environment where agents can safely run code, install packages, and execute shell commands.

Install Docker Images via CLI#

The easiest way to set up Docker images is using the built-in command:

# Pull Docker images from GitHub Container Registry
uv run massgen --setup-docker

This will pull:

  • ghcr.io/massgen/mcp-runtime:latest - Standard runtime image

  • ghcr.io/massgen/mcp-runtime-sudo:latest - Runtime with sudo support

Note

The --setup command will offer to run --setup-docker for you automatically.

Prerequisites:

  • Docker Desktop or Docker Engine must be installed and running

  • On macOS/Linux: docker info should work without sudo

  • On Windows: Docker Desktop must be running

Verifying Docker Setup:

# Check Docker is running
docker info

# Check MassGen images are available
docker images | grep massgen

You should see both mcp-runtime and mcp-runtime-sudo images listed.

When is Docker needed?

Docker is required when using:

  • command_line_execution_mode: docker in your config

  • Code-based tools with Docker isolation

  • The --quickstart command with Docker execution mode

If Docker isn’t available, --quickstart will automatically configure local execution mode (more restricted but still functional).

Skills Installation#

Skills enhance MassGen with additional capabilities like semantic search, LSP-based code understanding, and web scraping. You can install skills after setting up MassGen.

Manual Skills Installation#

If you prefer to install skills manually or need specific skills:

# Install openskills CLI
npm install -g openskills

# Install Anthropic skills collection
openskills install anthropics/skills --universal -y

# Skills are installed to ~/.agent/skills/

Development Scripts (Unix/macOS/Linux)#

For development installations, bash scripts are available that provide additional setup:

# Full development setup (dependencies, skills, Docker)
./scripts/init.sh

# Just install skills
./scripts/init_skills.sh

# With options
./scripts/init.sh --skip-docker  # Skip Docker image builds
./scripts/init.sh --help         # Show all options

Note

The bash scripts are Unix-only. Windows users should use massgen --setup-skills instead.

Verifying Skills Installation#

Check that skills are installed correctly:

# List installed skills
ls ~/.agent/skills/

# On Windows
dir %USERPROFILE%\.agent\skills\

You should see directories for each installed skill (e.g., pdf, xlsx, crawl4ai).

Optional CLI Tools#

Enhanced Capabilities#

Install these optional tools for enhanced MassGen capabilities:

Claude Code CLI#

Advanced coding assistant with comprehensive development tools:

npm install -g @anthropic-ai/claude-code

LM Studio#

Local model inference for running open-weight models:

For MacOS/Linux:

sudo ~/.lmstudio/bin/lms bootstrap

For Windows:

cmd /c %USERPROFILE%\.lmstudio\bin\lms.exe bootstrap

Verification Steps#

After installation, verify MassGen is correctly installed:

# Check MassGen is available
massgen --help

You should see the MassGen CLI help message with all available options.

Quick Test#

Try a simple query to verify everything works:

# Single agent mode (no config needed)
massgen --model gemini-2.5-flash "What is MassGen?"

# Or run the wizard and try your default config
massgen "Tell me about multi-agent systems"

Next Steps#

Great! You’ve installed MassGen. Here’s your learning path:

✅ You are here: Installation complete

⬜ Next: Running MassGen - Run your first command and see MassGen in action

⬜ Then: Configuration - Learn how to customize agent teams

⬜ Advanced: Interactive Multi-Turn Mode - Explore interactive conversations

Quick jump: Want to dive into examples? Check out Basic Examples for copy-paste configurations.

Troubleshooting#

Setup Wizard Not Appearing#

If the wizard doesn’t appear on first run:

# Manually trigger the setup wizard
massgen --init

# Or check if a config already exists (Unix/Mac)
ls ~/.config/massgen/config.yaml

# Windows
dir %USERPROFILE%\.config\massgen\config.yaml

To start fresh, remove the existing config and run again.

Python Version Issues#

If you encounter Python version errors:

# Check your Python version
python --version

# If below 3.11, install a newer version from python.org
# Then reinstall MassGen
pip install --upgrade massgen

Missing Example Configurations#

If --list-examples shows no results:

# Reinstall MassGen to ensure package data is included
pip install --force-reinstall massgen

# Verify installation
massgen --list-examples

API Key Errors#

If you see “API key not found” errors:

  1. Check your .env file exists:

    • Unix/Mac: ~/.config/massgen/.env

    • Windows: %USERPROFILE%\.config\massgen\.env

  2. Verify the key is correctly named (e.g., OPENAI_API_KEY)

  3. Re-run the wizard: massgen --init

For more help, visit our GitHub Issues or join our community.

Note

Existing MassGen users: If you previously used MassGen via git clone, all your existing workflows continue to work. See Running MassGen (Backwards Compatibility section) for details on command syntax and migration.

Contents