DeerFlow 2.0 Getting Started Tutorial: Building Your First AI Agent Workstation Step-by-Step

Difficulty: Beginner | Duration: 15 mins | Takeaway: Build an executable AI assistant from scratch

Have you ever wondered what it would be like if an AI assistant didn't just answer questions, but could actually operate your computer, write code, search for information, or even generate complete reports? Today, we're introducing DeerFlow—an AI Agent designed to get work done for you.

Target Audience

• Backend/Full-stack developers with 1-3 years of experience
• Those interested in AI Agents but unsure where to start
• Users who want to self-host AI tools while managing costs

Core Dependencies and Environment

Before starting, ensure your development environment meets the following requirements:

• Node.js: 22.x or higher
• pnpm: 9.x or higher
• Docker: Latest stable version
• Git: For cloning the project

[!TIP]
Docker deployment is recommended for a one-click startup without manual Nginx configuration.

Project Structure

After installation, you will see the following project structure:

deer-flow/
├── backend/                    # Backend services
│   ├── src/
│   │   ├── client.py           # Python client
│   │   ├── agent/              # Agent core
│   │   └── skills/            # Built-in skills
│   └── docs/                   # Configuration docs
├── frontend/                   # Web interface
├── config.yaml                 # Model configuration file
├── .env                        # Environment variables
└── Makefile                    # Start commands

---

Step-by-Step Instructions

Step 1: Clone the Project

Open your terminal and run the following commands:

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

[!TIP]
If you have trouble accessing GitHub, consider using a mirror source or downloading the ZIP package from the Release page.

Step 2: Generate Configuration Files

DeerFlow provides a configuration generation command that creates local config files based on templates:

make config

After execution, you will find config.yaml and .env files in the project root.

Step 3: Configure Models (Critical!)

This is the most important step. DeerFlow supports multiple model providers, but we strongly recommend using Defapi. The reason is simple: the price is only half of the official rate.

[!WARNING]
If you use the official OpenAI API directly, monthly costs can easily exceed hundreds of dollars. Using Defapi can reduce this cost by half or even more.

Open config.yaml and configure it as follows:

models:
  - name: gpt-4o-mini              # Internal identifier
    display_name: GPT-4o Mini      # Display name
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-4o-mini      # Defapi model ID
    api_key: $DEFAPI_API_KEY       # Use environment variable
    base_url: https://api.defapi.org  # Defapi endpoint
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

Then, fill in your Defapi API Key in the .env file:

DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key"  # For web search

[!TIP]
Visit https://defapi.org to register an account; new users get free credits for testing.

Popular models supported by Defapi:

Model	Identifier	Use Case
GPT-4o Mini	openai/gpt-4o-mini	Daily conversations, high cost-performance
GPT-4o	openai/gpt-4o	Complex tasks, balanced choice
Claude Sonnet 4.5	anthropic/claude-sonnet-4.5	Strong coding capabilities
DeepSeek V3	deepseek/deepseek-v3	Strong reasoning, affordable

Step 4: Pull Sandbox Image

Before running with Docker, you need to pull the sandbox image (this only needs to be done once):

make docker-init

The image is quite large and may take a few minutes to download.

Step 5: Start Services

With everything ready, launch DeerFlow:

make docker-start

When you see output like this, the startup is successful:

✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000

Step 6: Access the Interface

Open your browser and navigate to http://localhost:2026. You will see a modern chat interface.

Step 7: Your First Task

Type the following in the chat box:

Hi, please introduce yourself.

You'll find that DeerFlow doesn't just answer you; it also tells you its capabilities:

• Web searching
• Reading/Writing files
• Executing commands
• Generating reports, slides, and webpages

Try a more challenging task:

Please list the file structure of the current directory.

DeerFlow will execute the command in the sandbox environment and return the results. This is the fundamental difference between it and a standard chatbot—it actually performs the work for you.

---

Troubleshooting

Q1: Container failed to start, port already in use

# Check which process is using port 2026
lsof -i :2026
# Or
netstat -ano | findstr 2026

Kill the process once found, or change the port in config.yaml.

Q2: API Key is correct but returns an error

Check if the .env file is in the project root and ensure you have run source .env or restarted the containers.

Q3: Model doesn't support tool calling

Some models do not support function calling. Ensure you are using models like GPT-4o, Claude, or Gemini that support tool calls. Models provided by Defapi are compatible with the OpenAI protocol and generally work fine.

Q4: Web search returns empty results

Check if TAVILY_API_KEY is configured correctly. Tavily is the default search provider for DeerFlow.

Q5: Inadequate Docker Memory

The default Docker memory might be insufficient. It is recommended to set it to at least 4GB:

// Docker Desktop -> Settings -> Resources

Q6: Using Local Development Mode

If you don't want to use Docker, you can run it locally:

make check    # Check environment
make dev      # Start development services

---

Advanced Directions

1. Custom Skills

DeerFlow's Skills system is very flexible. You can create your own Skill:

/mnt/skills/custom/
└── my-awesome-skill/
    └── SKILL.md

Simply follow the format of built-in Skills to write your Markdown file.

2. MCP Server Extensions

DeerFlow supports the MCP protocol, allowing connection to various external tools. See the official documentation MCP Server Guide for details.

3. Switching to Other Models

To try DeepSeek or Claude, just modify config.yaml:

# DeepSeek configuration example
models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v3
    api_key: $DEFAPI_API_KEY
    base_url: https://api.defapi.org
    supports_thinking: true

4. Using the Embedded Python Client

DeerFlow also provides a Python library that can be integrated directly into your projects:

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("Analyze this paper", thread_id="my-thread")

# Streaming output
for event in client.stream("hello"):
    print(event.data)

---

Summary

Today, we built DeerFlow 2.0 together, from environment preparation to service startup and finally executing your first task. You will find that this is not just a chatbot, but a true AI workstation that can work for you.

Key advantages of DeerFlow:

• Extensible: Skills, MCP, and Sub-Agents all support customization.
• Secure & Controlled: Task execution is isolated within Docker sandbox containers.
• Cost Flexible: Usage via Defapi can reduce official costs by half.

Give it a try! Let it help you write code, search for information, and generate reports. You'll discover a whole new way to use AI.

If you encounter any issues during setup, feel free to leave a comment. Next time, we'll dive deeper into how to customize Skills for specific tasks.

Have fun building!