AdvancedAILangGraphLangChainPythonTypeScriptMulti-AgentFastAPINext.jsDocker

DeerFlow 2.0: SuperAgent Harness Setup

Set up DeerFlow 2.0, ByteDance's open-source long-horizon SuperAgent harness built on LangGraph and LangChain. Handle complex multi-step tasks with sandboxed execution, memory management, skills, and sub-agent orchestration.

Step 1
System Requirements
Before starting, ensure your system meets the minimum requirements. DeerFlow can be deployed locally for development or in production with higher specifications.
```
Local Development:
- CPU: 4 vCPU
- RAM: 8 GB
- Storage: 25 GB SSD
- OS: Linux, macOS, or Windows with WSL2

Production Server:
- CPU: 8 vCPU
- RAM: 16 GB
- Storage: 40 GB SSD
```

Step 2

Install Prerequisites

DeerFlow requires Python 3.12+, Node.js 22+, pnpm package manager, and uv for Python dependency management. Install these tools before proceeding.

# Install Node.js 22+ (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Install pnpm
npm install -g pnpm

# Install uv for Python package management
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify Python 3.12+ is installed
python3 --version

⚠ Heads up: Python 3.12 or higher is required. If your system has an older version, use pyenv or your package manager to install Python 3.12+.

Step 3
Clone the Repository
Clone the official DeerFlow repository from ByteDance's GitHub. Version 2.0 is a complete rewrite that shares no code with v1.
```
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
```
Step 4
Run Setup Wizard
DeerFlow includes an interactive setup wizard that configures your LLM provider preferences and system settings. This creates the necessary configuration files.
```
make setup
```
⚠ Heads up: The setup wizard will prompt you to select LLM providers (OpenAI, Anthropic, etc.). You'll need API keys for your chosen providers.

Step 5

Configure LLM Providers

Create a .env file in the backend directory with your LLM API keys. DeerFlow supports multiple providers including OpenAI, Anthropic Claude, and others.

# backend/.env

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic Configuration (recommended for best results)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Optional: Other provider keys
# GROQ_API_KEY=your_groq_key
# GOOGLE_API_KEY=your_google_key

# Web search capabilities (optional)
TAVILY_API_KEY=your_tavily_key
FIRECRAWL_API_KEY=your_firecrawl_key

Step 6
Docker Deployment (Recommended)
Docker is the recommended deployment method as it handles all dependencies and provides consistent environments. Initialize and start the containers.
```
# Initialize Docker environment
make docker-init

# Start DeerFlow services
make docker-start

# View logs
make docker-logs

# Stop services when needed
make docker-stop
```
Step 7
Alternative: Local Development Setup
For local development without Docker, install dependencies directly on your system. This gives you more control but requires managing dependencies manually.
```
# Install all dependencies
make install

# Start development servers
make dev

# This starts:
# - Backend (FastAPI) on port 8001
# - Frontend (Next.js) on port 3000
# - Nginx reverse proxy on port 2026
```
⚠ Heads up: Local development requires nginx to be installed and configured. The make dev command handles this, but you may need to install nginx separately on some systems.
Step 8
Verify Installation
Run the built-in doctor command to check that all prerequisites are properly installed and configured.
```
make doctor
```
Step 9
Access the Web Interface
Once DeerFlow is running, access the web interface through your browser. The unified entry point is served by nginx on port 2026.
```
# Open in your browser:
http://localhost:2026

# Direct API access (if needed):
# Backend API: http://localhost:8001
# Frontend dev: http://localhost:3000
```

Step 10

Understanding the Architecture

DeerFlow uses a multi-layer architecture built on LangGraph and LangChain. The Gateway API (FastAPI) manages the embedded agent runtime, while the Next.js frontend provides the user interface. Nginx routes all requests through port 2026.

Architecture Components:

1. Lead Agent - Main orchestrator with dynamic model selection
2. Middleware Chain - 9 ordered processors for context, memory, sandboxing
3. Sandbox System - Isolated code execution (local filesystem or Docker)
4. Subagent System - Parallel task delegation (up to 3 concurrent)
5. Memory System - LLM-powered persistent context retention
6. Skills System - Extensible capabilities (research, reports, slides, etc.)
7. MCP Integration - Model Context Protocol server support

Step 11

Configure Skills and Tools

DeerFlow comes with built-in skills for common tasks. You can also install additional skills through the Skills API or by adding skill directories.

# Skills are located in:
ls skills/public/

# Built-in skills include:
# - Web research and data gathering
# - Report and document generation
# - Slide deck creation
# - Image and video generation
# - Code execution and debugging
# - File operations and transformations

Step 12

Test with a Simple Task

Test your DeerFlow installation by running a simple research task through the web interface or API.

# Example API test using curl:
curl -X POST http://localhost:2026/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Research the top 3 programming languages in 2026 and create a summary report",
    "thread_id": null
  }'

Step 13

Configure Memory and Context

DeerFlow's memory system persists user preferences and conversation context. Memory data is stored as JSON files with automatic cache invalidation.

Memory System Features:

- LLM-powered context analysis
- Automatic fact and preference extraction
- Thread-local memory isolation
- Debounced storage updates
- mtime-based cache invalidation

Memory is automatically managed per thread and injected into agent prompts for context-aware responses.

Step 14

Working with Subagents

DeerFlow's lead agent can spawn up to 3 concurrent subagents for parallel task execution. Subagents have 15-minute timeouts and can be specialized (general-purpose or bash-specialist).

Subagent Workflow:

1. Lead agent analyzes the task
2. Breaks complex tasks into subtasks
3. Determines which can run in parallel
4. Spawns specialized subagents
5. Synthesizes results from all agents

This enables efficient handling of complex, multi-step tasks that would take hours for a single agent.

Step 15

File Upload and Processing

DeerFlow automatically converts uploaded documents to Markdown for LLM processing. Supported formats include PDF, PowerPoint, Excel, and Word documents.

# Supported file formats:
# - PDF (.pdf)
# - PowerPoint (.ppt, .pptx)
# - Excel (.xls, .xlsx)
# - Word (.doc, .docx)

# Files are processed through the markitdown library
# and converted to LLM-friendly Markdown format

Step 16

Production Deployment Considerations

For production deployments, configure proper authentication, rate limiting, and resource allocation. Use environment variables to manage secrets securely.

# Production checklist:
# - Set strong API keys and rotate regularly
# - Configure CORS policies appropriately
# - Set up monitoring and logging
# - Allocate sufficient resources (8+ vCPU, 16+ GB RAM)
# - Use Docker for consistent deployments
# - Set up reverse proxy with SSL/TLS
# - Configure backup for memory/thread data
# - Implement rate limiting on API endpoints

⚠ Heads up: Never expose your LLM API keys in client-side code or commit them to version control. Use environment variables and secure secret management.

Step 17

Monitoring and Debugging

DeerFlow provides logging and debugging capabilities through the FastAPI backend. Monitor agent execution, sandbox operations, and API requests.

# View backend logs
make docker-logs

# For local development:
# Backend logs appear in the terminal running make dev

# Debug mode can be enabled in backend configuration
# for more verbose logging output

Step 18

Advanced: MCP Server Integration

DeerFlow supports the Model Context Protocol (MCP), allowing integration with a growing ecosystem of MCP-compatible tools without modifying core code.

# MCP configuration is managed through the Gateway API
# Endpoints available:
# - POST /api/mcp/configure
# - GET /api/mcp/servers
# - POST /api/mcp/install

# MCP extends DeerFlow's capabilities with:
# - Database connectors
# - External APIs
# - Custom tools and integrations
# - Third-party services

Step 19

Technology Stack Summary

DeerFlow is built on a modern stack combining Python for the backend agent system and TypeScript for the frontend interface.

Core Technologies:

- Python 3.12+ (73.5% of codebase)
- TypeScript (14.9% of codebase)
- LangGraph 1.0.6+ (agent orchestration)
- LangChain 1.2.3+ (LLM interactions)
- FastAPI 0.115.0+ (backend API)
- Next.js (frontend web interface)
- Nginx (reverse proxy)
- Docker (containerization)

Key Libraries:
- langchain-mcp-adapters (MCP integration)
- agent-sandbox (isolated execution)
- markitdown (document conversion)
- Tavily & Firecrawl (web research)

Step 20

Troubleshooting Common Issues

Common setup and runtime issues with their solutions.

Issue: Port 2026 already in use
Solution: Stop existing nginx or change port in nginx config

Issue: Python version mismatch
Solution: Use pyenv to install Python 3.12+

Issue: Node.js version too old
Solution: Use nvm to install Node.js 22+

Issue: API key errors
Solution: Verify .env file exists in backend/ directory

Issue: Docker containers won't start
Solution: Run 'make docker-clean' then 'make docker-init'

Issue: Sandbox execution failures
Solution: Ensure proper permissions on thread directories

DeerFlow 2.0: SuperAgent Harness Setup

System Requirements

Install Prerequisites

Clone the Repository

Run Setup Wizard

Configure LLM Providers

Docker Deployment (Recommended)

Alternative: Local Development Setup

Verify Installation

Access the Web Interface