Quick Start Guide

Get DeerFlow running in minutes with Docker or local development setup

Quick Start

Get DeerFlow up and running in just a few steps. This guide covers both Docker (recommended) and local development setups.

Prerequisites: Git, and either Docker (for Docker setup) or Node.js 22+, pnpm, uv, and nginx (for local development).

Step 1: Clone the Repository

First, clone the DeerFlow repository:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

Step 2: Configuration

Generate Configuration Files

Run the following command from the project root directory:

make config

This command creates local configuration files based on example templates:

• config.yaml - Main application configuration
• .env - Environment variables
• frontend/.env - Frontend environment variables

The make config command will abort if configuration files already exist to prevent overwriting your settings.

Configure Your Model

Edit config.yaml and define at least one model. Here’s an example with OpenAI’s GPT-4:

OpenAI (GPT-4)

models:
  - name: gpt-4                       # Internal identifier
    display_name: GPT-4               # Human-readable name
    use: langchain_openai:ChatOpenAI  # LangChain class path
    model: gpt-4                      # Model identifier for API
    api_key: $OPENAI_API_KEY          # API key (use env var)
    max_tokens: 4096                  # Maximum tokens per request
    temperature: 0.7                  # Sampling temperature
    supports_vision: true             # Enable vision support

models:
  - name: claude-3-5-sonnet
    display_name: Claude 3.5 Sonnet
    use: langchain_anthropic:ChatAnthropic
    model: claude-3-5-sonnet-20241022
    api_key: $ANTHROPIC_API_KEY
    max_tokens: 8192
    supports_vision: true

models:
  - name: deepseek-v3
    display_name: DeepSeek V3 (Thinking)
    use: src.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-reasoner
    api_key: $DEEPSEEK_API_KEY
    max_tokens: 16384
    supports_thinking: true
    supports_vision: false
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

models:
  - name: gemini-2.5-pro
    display_name: Gemini 2.5 Pro
    use: langchain_google_genai:ChatGoogleGenerativeAI
    model: gemini-2.5-pro
    google_api_key: $GOOGLE_API_KEY
    max_tokens: 8192
    supports_vision: true

Environment Variables: Config values starting with $ are resolved from environment variables (e.g., $OPENAI_API_KEY).

Set API Keys

Choose one of the following methods to configure your API keys:

Option A: .env File (Recommended)

Edit the .env file in the project root:

.env

TAVILY_API_KEY=your-tavily-api-key
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
# Add other provider keys as needed

Option B: Shell Export

Export environment variables in your shell:

export OPENAI_API_KEY=your-openai-api-key
export TAVILY_API_KEY=your-tavily-api-key

Option C: Direct in config.yaml

Edit config.yaml directly (not recommended for production):

models:
  - name: gpt-4
    api_key: sk-your-actual-api-key-here  # Replace placeholder

Not recommended for production. Use environment variables instead.

Step 3: Running the Application

Docker (Recommended)

The fastest way to get started with a consistent environment.

1. Initialize Docker

   Pull the sandbox image (only needed once or when the image updates):

   make docker-init
   

   This downloads the sandbox container image (~500MB+) used for isolated code execution.

2. Start Services

   Start all services:

   make docker-start
   

   This command automatically detects your sandbox mode from config.yaml and starts the appropriate services:

   • Local/Docker sandbox mode: Starts frontend, gateway, langgraph, and nginx
   • Provisioner mode: Also starts the provisioner service for Kubernetes-based sandboxes
3. Access DeerFlow

   Open your browser and navigate to:

   http://localhost:2026
   

   You should see the DeerFlow chat interface.

Useful Docker Commands

# Stop all services
make docker-stop

# View all logs
make docker-logs

# View frontend logs only
make docker-logs-frontend

# View gateway logs only
make docker-logs-gateway

See the CONTRIBUTING.md guide for detailed Docker development workflows.

Local Development

Run services locally without Docker for faster iteration.

1. Check Prerequisites

   Verify all required tools are installed:

   make check
   

   This verifies:

   • Node.js 22+
   • pnpm (JavaScript package manager)
   • uv (Python package manager)
   • nginx (reverse proxy)

   If any tools are missing, the command provides installation instructions.

2. Install Dependencies

   Install frontend and backend dependencies:

   make install
   

   This runs:

   • cd backend && uv sync - Backend Python dependencies
   • cd frontend && pnpm install - Frontend JavaScript dependencies
3. (Optional) Pre-pull Sandbox Image

   If using Docker-based sandbox, pre-pull the container image:

   make setup-sandbox
   

   This is optional but recommended to avoid delays during first use.

4. Start Services

   Start all services in development mode:

   make dev
   

   This starts:

   • LangGraph Server (port 2024) - Agent runtime
   • Gateway API (port 8001) - REST API for models, skills, memory
   • Frontend (port 3000) - Next.js web interface
   • Nginx (port 2026) - Reverse proxy
5. Access DeerFlow

   Open your browser and navigate to:

   http://localhost:2026
   

   You should see the DeerFlow chat interface.

Development Workflow

Logs are written to the logs/ directory:

# View logs
tail -f logs/langgraph.log
tail -f logs/gateway.log
tail -f logs/frontend.log
tail -f logs/nginx.log

# Stop all services
make stop

# Clean up logs and processes
make clean

Press Ctrl+C in the terminal running make dev to stop all services gracefully.

Step 4: Verify Installation

Once DeerFlow is running, verify the installation:

1. Check the Interface

   Navigate to http://localhost:2026 and ensure the chat interface loads.

2. Send a Test Message

   Type a simple message like “Hello, can you help me?” and verify the agent responds.

3. Check Model Configuration

   Look for the model selector in the interface to confirm your configured models are available.

Advanced Configuration

Sandbox Mode

DeerFlow supports multiple sandbox execution modes:

Local Execution (Default)

Runs sandbox code directly on the host machine. Simple but less isolated.

config.yaml

sandbox:
  use: src.sandbox.local:LocalSandboxProvider

Docker Execution

Runs sandbox code in isolated Docker containers. Recommended for most use cases.

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  
  # Optional: Container image to use
  # image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
  
  # Optional: Base port for sandbox containers
  # port: 8080
  
  # Optional: Auto-start containers
  # auto_start: true
  
  # Optional: Container name prefix
  # container_prefix: deer-flow-sandbox

Platform Support:

• macOS: Automatically uses Apple Container if available, falls back to Docker
• Linux/Windows: Uses Docker

Kubernetes Provisioner

Each sandbox gets a dedicated Pod in Kubernetes, managed by the provisioner service. For production or advanced users.

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

When using provisioner mode, make docker-start automatically starts the provisioner service.

See the Sandbox Configuration Guide for detailed instructions.

MCP Servers

DeerFlow supports configurable MCP (Model Context Protocol) servers to extend capabilities.

Supported transports:

• stdio - Command-based servers (e.g., GitHub, filesystem)
• HTTP - REST API servers with OAuth support
• SSE - Server-Sent Events servers

stdio Server Example

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    }
  }
}

{
  "mcpServers": {
    "secure-api": {
      "enabled": true,
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "grant_type": "client_credentials",
        "client_id": "$MCP_CLIENT_ID",
        "client_secret": "$MCP_CLIENT_SECRET"
      }
    }
  }
}

See the MCP Server Guide for detailed setup instructions.

Common Issues

Port Already in Use

If you see errors about ports 2024, 2026, 3000, or 8001 being in use:

# Find and kill processes using these ports
lsof -ti:2026 | xargs kill -9
lsof -ti:2024 | xargs kill -9
lsof -ti:8001 | xargs kill -9
lsof -ti:3000 | xargs kill -9

# Or use make clean
make clean

Missing Dependencies

If make check reports missing tools:

# Install Node.js 22+
# Visit: https://nodejs.org/

# Install pnpm
npm install -g pnpm

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install nginx
# macOS:
brew install nginx
# Ubuntu:
sudo apt install nginx

Config File Not Found

Ensure config.yaml is in the project root:

# Check if config exists
ls -la config.yaml

# If missing, run make config
make config

Config search order:

1. DEER_FLOW_CONFIG_PATH environment variable (if set)
2. backend/config.yaml (current directory)
3. config.yaml (parent directory - recommended)

Docker Image Pull Fails

If make docker-init fails to pull the sandbox image:

# Try pulling manually
docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# Or use a mirror (China users)
# Update config.yaml:
sandbox:
  image: your-mirror-registry/all-in-one-sandbox:latest

API Key Not Working

Verify your API keys are correctly set:

# Check environment variables
echo $OPENAI_API_KEY

# Verify .env file
cat .env

# Test config loading (from backend directory)
cd backend
python -c "from src.config import get_app_config; print(get_app_config().models[0].api_key)"

What’s Next?

Now that DeerFlow is running, explore these guides:

Configuration Guide

Deep dive into models, tools, sandbox, and memory configuration

Skills Management

Learn how to use, create, and install custom skills

Architecture

Understand DeerFlow’s technical architecture

API Reference

Complete API documentation for integration

Need help? Report issues at github.com/bytedance/deer-flow/issues