How to run DeerFlow 2.0: getting started with ByteDance's open-source long-horizon SuperAgent locally

bytedance/deer-flow is ByteDance’s open-source long-horizon SuperAgent harness. It is not aimed at short Q&A. It targets long tasks that require research, coding, tool use, sandbox execution, memory, and sub-agents.

Project repository:

https://github.com/bytedance/deer-flow

Official site:

https://deerflow.tech

Clone the Project

The README gives these basic steps:

1
2


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

For local development, start with:

1

make setup

Configure Models

DeerFlow supports different model providers. The README includes OpenAI / OpenRouter-style configuration examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

If you use Claude Code OAuth, export the environment first:

1

eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"

Common API keys:

1
2


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

Start with Docker

The README recommends Docker. First initialize the sandbox image:

1

make docker-init

Start the service:

1

make docker-start

For production deployment, follow the Docker production section in the README for build/start/stop.

Suitable Tasks

DeerFlow is better suited for:

Research tasks that need search, synthesis, and citations.
Long coding tasks that need sandbox execution and multiple tools.
Multi-step content production, such as research, planning, generation, and verification.
Workflows that need sub-agents or skill composition.

Usage Suggestions

Do not start with a huge task like “build a complete product.” Give it a small, verifiable task first, such as “research an open-source library and generate usage examples.” After confirming that the model, search, sandbox, and tool calls all work, gradually extend the task length.