Installation

Install DeerFlow and set up your development environment

Prerequisites

Before installing DeerFlow, ensure you have the required tools installed on your system.

Required Tools

Node.js 22+

DeerFlow requires Node.js version 22 or higher for the frontend development server.

Installation:

• Download from nodejs.org
• Or use a version manager like nvm

Verify installation:

node -v  # Should show v22.x.x or higher

pnpm

pnpm is the package manager used for frontend dependencies.

Installation:

npm install -g pnpm

Or visit pnpm.io/installation

Verify installation:

pnpm -v

uv (Python Package Manager)

uv is a fast Python package manager used for backend dependencies.

Installation:

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

Or visit docs.astral.sh/uv

Verify installation:

uv --version

nginx

nginx is used as a reverse proxy to unify all services on port 2026.

Installation:

macOS

brew install nginx

sudo apt install nginx

sudo yum install nginx

Or visit nginx.org/en/download.html

Verify installation:

nginx -v

Docker (Optional)

Docker is required if you plan to use Docker-based sandbox execution or Docker development mode.

Installation:

• Download Docker Desktop
• On macOS, you can also use OrbStack as a lightweight alternative

Verify installation:

docker --version

Quick Check

DeerFlow provides a convenient command to verify all prerequisites:

make check

This will check for:

• Node.js 22+
• pnpm
• uv
• nginx

And report which tools are missing or need to be updated.

Installation Steps

1. Clone the Repository

   Clone DeerFlow from GitHub:

   git clone https://github.com/bytedance/deer-flow.git
   cd deer-flow
   
2. Generate Configuration Files

   Generate local configuration files from templates:

   make config
   

   This creates:

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

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

3. Configure Your Model

   Edit config.yaml and configure at least one LLM model:

   config.yaml

   models:
     - name: gpt-4
       display_name: GPT-4
       use: langchain_openai:ChatOpenAI
       model: gpt-4
       api_key: $OPENAI_API_KEY
       max_tokens: 4096
       temperature: 0.7
       supports_vision: true
   

   See Configuration Guide for more model options.

4. Set API Keys

   Set your API keys using one of these methods:

   .env File (Recommended)

   Edit the .env file in the project root:

   .env

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

   Environment Variables

   Export environment variables in your shell:

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

   config.yaml (Not Recommended)

   Directly in config.yaml (not recommended for production):

   models:
     - name: gpt-4
       api_key: your-actual-api-key-here
   

   Never commit API keys to version control. Use environment variables instead.

5. Install Dependencies

   Install both frontend and backend dependencies:

   make install
   

   This runs:

   • cd backend && uv sync - Install Python dependencies
   • cd frontend && pnpm install - Install Node.js dependencies
6. (Optional) Pre-pull Sandbox Image

   If you plan to use Docker-based sandbox execution, pre-pull the container image:

   make setup-sandbox
   

   This downloads the sandbox container image:

   enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
   

   This step is optional but recommended. It ensures the sandbox image is available when you need it, avoiding delays during first use.

Verify Installation

Start the development server to verify everything is working:

make dev

You should see output indicating all services have started:

==========================================
  DeerFlow is ready!
==========================================

  🌐 Application: http://localhost:2026
  📡 API Gateway: http://localhost:2026/api/*
  🤖 LangGraph:   http://localhost:2026/api/langgraph/*

Open http://localhost:2026 in your browser to access DeerFlow.

Next Steps

Docker Setup

Set up Docker development environment for isolated services

Local Development

Learn about running services locally and development workflow

Configuration

Explore configuration options for models, tools, and sandbox

Creating Skills

Extend DeerFlow with custom skills

Troubleshooting

make check fails with missing tools

Install the missing tools as indicated by the error message. Each tool has specific installation instructions shown in the output.

Config file not found error

Ensure config.yaml exists in the project root directory:

ls config.yaml

If missing, run:

make config

Invalid API key error

Verify your API keys are correctly set:

• Check .env file has the correct keys
• Ensure environment variables are exported
• Verify the API key is valid with your provider

Port already in use

If port 2026, 8001, 3000, or 2024 is already in use:

1. Stop any existing DeerFlow processes:

   make stop
   

2. Find and kill the process using the port:

   lsof -ti:2026 | xargs kill -9